layover 0.1.0.dev0__py3-none-any.whl

layover/cost/generalized.py

@@ -0,0 +1,1207 @@
+"""Generalized cost: the ranking objective (DESIGN §8).
+
+    generalized_cost = money_total          # fares, ancillaries, hotels, lounges
+                     + time_cost            # hours you don't get back, x wage rate
+                     + discomfort           # unpleasantness, at its own price
+                     + stopover_net + flexibility + borders + ground
+                     + expected_risk        # P(miss) x consequence, incl. stakes
+
+Three families, kept apart because they answer different questions: **time** (what
+an hour is worth), **discomfort** (how much you mind things — not multiplied by the
+wage rate), and **risk** (probabilities times consequences, including what missing a
+hard constraint would cost). Nothing is a "premium" any more, and nothing is a mode.
+
+One scalar band, in the normalization currency, with every term itemized so a
+ranking can be explained in euros and argued with. `money_total` — what actually
+leaves the account — is always carried alongside and never hidden.
+
+Pricing is a pure function of (plan, context), so the same plan can be priced under
+different valuations without mutating anything.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field, replace
+from datetime import date, datetime, timedelta
+from enum import StrEnum
+
+from layover.cost import borders as borders_mod
+from layover.cost import curve
+from layover.cost import lounge as lounge_mod
+from layover.cost.borders import PartyBorder, Regime, RegimeTable
+from layover.cost.connection import FeasibilityVerdict, assess
+from layover.cost.constraints import ConstraintKind, ConstraintViolation, HardConstraint
+from layover.cost.constraints import check as check_constraints
+from layover.cost.delay import DelayEstimate, DelayTable, PunctualityObservation, blend, p_miss
+from layover.interact.assumptions import Assumption, AssumptionLog, Option
+from layover.models import (
+    BaggageProfile,
+    Connection,
+    Protection,
+    RiskAnnotation,
+    RiskKind,
+    Segment,
+    TripPlan,
+)
+from layover.money import Band, band_sum
+from layover.prefs.profile import PreferenceProfile
+from layover.prefs.travelers import Party
+
+
+class CostKind(StrEnum):
+    FARE = "fare"
+    DISCOMFORT = "discomfort"
+    ANCILLARY = "ancillary"
+    TRAVEL_TIME = "travel_time"
+    INVOLUNTARY_WAIT = "involuntary_wait"
+    STOPOVER = "stopover"
+    DATE_FLEXIBILITY = "date_flexibility"
+    DURATION_DEVIATION = "duration_deviation"
+    TIME_OF_DAY = "time_of_day"
+    EXPECTED_DELAY = "expected_delay"
+    BORDER = "border"
+    GROUND_TRANSFER = "ground_transfer"
+    LOUNGE = "lounge"
+    RISK_PREMIUM = "risk_premium"
+
+
+@dataclass(frozen=True, slots=True)
+class CostLine:
+    kind: CostKind
+    amount: Band
+    note: str
+    traveler_id: str | None = None
+
+    def __str__(self) -> str:
+        who = f" [{self.traveler_id}]" if self.traveler_id else ""
+        return f"{self.kind:<18} {self.amount!s:>12}  {self.note}{who}"
+
+
+@dataclass(frozen=True, slots=True)
+class StopWindows:
+    """One planned stop, and the preferences attached to it.
+
+    Supplied by the intent, which is the only thing that knows what was asked for.
+    Callables rather than models so the cost model needs no import of the intent
+    layer — and `None` for a window nobody stated, which is the normal case.
+    """
+
+    place: str
+    arrive: Callable[[datetime], DateCost | None] | None = None
+    depart: Callable[[datetime], DateCost | None] | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class StopMoments:
+    """Where a planned stop actually landed in a candidate itinerary."""
+
+    place: str
+    arrive: datetime | None = None
+    depart: datetime | None = None
+
+
+def align(plan: TripPlan, places: Sequence[str]) -> list[StopMoments]:
+    """Match a plan's segments against the journey's planned stops, in order.
+
+    An itinerary has many departures and arrivals; only the ones at planned stops are
+    choices the owner expressed a preference about. The rest are connections, whose
+    times the routing decides — and pricing those against the same window charges a
+    one-stop itinerary twice for one decision, since the connecting leg also departs
+    on a day the window covers.
+
+    Matched **in order and by place**, never by index: a candidate with two connections
+    has more legs than one with none, so position means something different in each.
+    Repeated places (out of BUD, home to BUD) are handled by the ordering.
+    """
+    segments = plan.segments
+    if not segments or not places:
+        return []
+    moments = [StopMoments(places[0], None, segments[0].depart)]
+    at = 0
+    for index, segment in enumerate(segments):
+        if at + 1 >= len(places):
+            break
+        if segment.destination != places[at + 1]:
+            continue  # a connection: the routing's business, not a stated preference
+        at += 1
+        onward = segments[index + 1].depart if index + 1 < len(segments) else None
+        moments.append(StopMoments(places[at], segment.arrive, onward))
+    return moments
+
+
+@dataclass(frozen=True, slots=True)
+class DateCost:
+    """What one departure moment costs, and whether the moment mattered.
+
+    `timed` is only for the explanation: writing "departs 2026-09-23 13:45" against a
+    window that speaks in whole days would claim a precision the preference never had,
+    and the whole point of the itemized table is that every number can be defended.
+    """
+
+    amount: float
+    timed: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class StopoverRequest:
+    """A stopover that is wanted — from the intent, a wishlist, or an answer.
+
+    `source` matters for the report: a stopover the owner asked for in advance and
+    one they accepted when the routing offered it are the same arithmetic but not
+    the same story.
+    """
+
+    place: str
+    min_nights: int = 1
+    max_nights: int = 3
+    ideal_nights: int | None = None
+    """The length actually wanted. Two nights in Istanbul is a stopover; one is a
+    rushed hotel run and four is a small holiday, and the difference is worth pricing
+    (§8.4). Inferred from the bounds when it is not stated."""
+    cost_at_tolerance: float | None = None
+    tolerance_nights: float | None = None
+    net_at_ideal: float = 0.0
+    """What a stay of the ideal length is worth, net, as one signed number (§8.3).
+
+    Negative means you would pay for it. Net because a hotel rate is guessable and
+    what the place is worth to *you* is not, and only the difference ever ranks
+    anything. This is the only cost in the model allowed below zero."""
+    source: str = "intent"
+    """intent | wishlist | asked"""
+
+    def bounds(self) -> curve.Bounds:
+        return curve.resolve(
+            self.min_nights, self.ideal_nights, self.max_nights, spread=self.tolerance_nights
+        )
+
+    def cost_of(self, nights: int, *, scale: float) -> float | None:
+        """The whole cost of this stop: what it is worth, and how far off the length is.
+
+        One function, no per-night rate. The marginal night is the derivative, which
+        starts at zero and grows — so the first night past the ideal is nearly free and
+        the tenth is not (§8.3).
+        """
+        amount = self.cost_at_tolerance if self.cost_at_tolerance is not None else scale
+        return curve.cost(
+            nights,
+            self.bounds(),
+            scale=amount,
+            tolerance=self.tolerance_nights,
+            offset=self.net_at_ideal,
+        )
+
+    def breakeven(self, *, scale: float) -> tuple[float, float] | None:
+        amount = self.cost_at_tolerance if self.cost_at_tolerance is not None else scale
+        if not amount:
+            return None
+        return curve.breakeven(
+            self.bounds(),
+            scale=amount,
+            tolerance=self.tolerance_nights,
+            offset=self.net_at_ideal,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class StopoverOpportunity:
+    """A stopover nobody asked for, because nobody knew it was on offer.
+
+    Real searches work backwards from the routing: a BUD–Dubai fare turns out to
+    connect in Santorini, a BUD–Bogotá one in Punta Cana, and *that* is when the
+    traveller decides they want two nights there. Treating such a gap as dead
+    layover time silently throws away the best thing about the itinerary, and
+    treating it as a wanted stopover invents a holiday nobody agreed to.
+
+    So it is neither: it is a priced question (§10). `net_ceiling` is the honest form
+    of that question — not "do you like Santorini?" but "would two nights there cost
+    you more than €200 net?", which is answerable, comparable, and contains no
+    lodging rate we had to invent on the owner's behalf (§8.3).
+    """
+
+    place: str
+    nights: int
+    hours: float
+    as_wait_cost: float
+    """What the gap costs treated as an involuntary layover."""
+    net_ceiling: float
+    """The most the stay may cost you, net, and still beat sitting it out.
+
+    Equal to what the wait costs, because taking the stop replaces that cost with this
+    one. Stated as a ceiling on *net* cost rather than a floor on value, since the
+    hotel is inside the owner's number now — asking "is a night worth €35?" required
+    us to have assumed a lodging rate, which was never ours to assume (§8.3)."""
+
+    def question(self) -> str:
+        return (
+            f"This routing sits {self.hours:.0f}h in {self.place}. Taking it as a "
+            f"{self.nights}-night stop beats waiting unless the stay costs you more "
+            f"than {self.net_ceiling:.0f} net — hotel minus whatever it is worth to "
+            f"be there. Take it?"
+        )
+
+
+@dataclass(slots=True)
+class PricingContext:
+    """Everything pricing needs that is not the plan itself."""
+
+    prefs: PreferenceProfile
+    """The trip's default valuations. Soft prices only — hard requirements are
+    `constraints`, and what missing them costs is `prefs.constraints` (§8.1)."""
+    party: Party
+    constraints: list[HardConstraint] = field(default_factory=list)
+    """Checked, never priced: a plan that misses the conference is not expensive."""
+    prefs_by_leg: dict[int, PreferenceProfile] = field(default_factory=dict)
+    """Per-leg valuation overrides, keyed by leg index across the whole plan.
+
+    Not a "mode" — just these numbers with a few changed, because time can be worth
+    more on the way to something than on the way home."""
+    destinations: frozenset[str] = frozenset()
+    """Where the trip is *going*. The gap there is the point of the whole exercise.
+
+    Without this, a return itinerary's four nights at the destination are read as a
+    92-hour layover and charged as dead time — which is not a rounding error, it is
+    the trip itself priced as suffering. Caught the first time the model met a real
+    multi-ticket return (AZair, BUD-LIS)."""
+    baggage_profile: BaggageProfile = BaggageProfile.CABIN_BAG
+    stopovers: dict[str, StopoverRequest] = field(default_factory=dict)
+    """Stopovers already wanted, by place — from the intent or an answered question."""
+    stopover_interest: dict[str, float] = field(default_factory=dict)
+    """Per-search additions to the config wishlist (`prefs.stopover.net`): place ->
+    net cost of a stay there, negative for wanted. A routing through one of these is
+    a wanted stop without asking, because the question was already answered."""
+    stopover_candidate_min_hours: float | None = None
+    """Override for `prefs.stopover.candidate_min_hours`; None uses config."""
+    offer_stopovers: bool | None = None
+    """Override for `prefs.stopover.offer`; None uses config."""
+    date_costs: dict[date, float] = field(default_factory=dict)
+    """Flexibility cost per outbound/inbound departure date (DESIGN §8.4).
+
+    Day granularity: what the best departure moment on that date would cost."""
+    journey: list[StopWindows] = field(default_factory=list)
+    """The planned stops in order, each with whatever windows were stated.
+
+    There is no outbound and no inbound here. A trip is stops and the legs between
+    them; "the return" is a leg home, and an open jaw or a four-city trip is the same
+    object with a different list (§8.3). Direction survives only in `Offer`, because a
+    round trip is a product airlines sell — not a fact about the journey."""
+    departure_cost: Callable[[datetime], DateCost | None] | None = None
+    """Legacy single-window entry point, used when no journey is supplied."""
+    stopover_length_scale: float = 0.0
+    """Scale for the stopover-length curve when a spec does not price its own."""
+    duration_cost: Callable[[int], float | None] | None = None
+    """Trip length in nights, priced by the intent's own window when it stated one.
+
+    Departure, arrival and length are three quantities of which any two fix the third,
+    so an intent normally states two — and when it states all three, each is priced on
+    its own terms rather than one being derived and silently double-counted."""
+    """The same preference at the resolution the itinerary actually has.
+
+    A window may name times as well as dates — "ideally airborne by 09:00, not before
+    06:00" — and then two flights on the same day are not the same choice. Supplied by
+    the intent (`TravelIntent.departure_cost`) and consulted first; `date_costs` is
+    what remains when a window speaks only in days."""
+    preferred_nights: int | None = None
+    delay_table: DelayTable = field(default_factory=DelayTable.fallback)
+    punctuality: dict[str, PunctualityObservation] = field(default_factory=dict)
+    """Keyed by "CARRIER+NUMBER"; empty before Phase 3 (DESIGN §8.5)."""
+    regimes: RegimeTable | None = None
+    transit_countries: dict[str, str] = field(default_factory=dict)
+    """Airport -> ISO country. Kept explicit so the cost model needs no airport DB."""
+    lounge_airports: frozenset[str] = frozenset()
+    """Airports where the party has lounge access in the terminal actually used."""
+    long_haul_hours: float = 6.0
+    ancillary_estimate: Band | None = None
+    """Baggage/ancillary adjustment from the fee table (M2); None = nothing known."""
+
+    @property
+    def checked_bag(self) -> bool:
+        return self.baggage_profile is BaggageProfile.CABIN_PLUS_CHECKED
+
+    @property
+    def offers_stopovers(self) -> bool:
+        if self.offer_stopovers is not None:
+            return self.offer_stopovers
+        return self.prefs.stopover.offer
+
+    @property
+    def candidate_min_hours(self) -> float:
+        if self.stopover_candidate_min_hours is not None:
+            return self.stopover_candidate_min_hours
+        return self.prefs.stopover.candidate_min_hours
+
+    def interest_in(self, place: str) -> float | None:
+        """Net cost of a stay in this place, if it has been valued in advance.
+
+        Per-search entries win over config. Negative means wanted (§8.3).
+        """
+        if place in self.stopover_interest:
+            return self.stopover_interest[place]
+        return self.prefs.stopover.net.get(place)
+
+    def delay_for(self, segment: Segment) -> DelayEstimate:
+        long_haul = segment.duration.total_seconds() / 3600 >= self.long_haul_hours
+        prior = self.delay_table.prior_for_hour(
+            segment.local_departure_hour, long_haul=long_haul
+        )
+        key = f"{segment.carrier}{segment.flight_number}"
+        return blend(
+            prior,
+            self.punctuality.get(key),
+            pseudo_observations=self.prefs.delay.prior_pseudo_observations,
+        )
+
+    def country_of(self, airport: str) -> str | None:
+        return self.transit_countries.get(airport)
+
+    def prefs_for_leg(self, leg_index: int) -> PreferenceProfile:
+        """The valuations that apply to one leg, defaulting to the trip's."""
+        return self.prefs_by_leg.get(leg_index, self.prefs)
+
+
+@dataclass(slots=True)
+class PlanCost:
+    """The priced plan: total, itemization, risks, and what had to be assumed."""
+
+    lines: list[CostLine]
+    money_total: Band
+    risks: list[RiskAnnotation]
+    infeasible_reasons: list[str]
+    verdicts: list[FeasibilityVerdict]
+    borders: list[PartyBorder]
+    notes: list[str]
+    violations: list[ConstraintViolation] = field(default_factory=list)
+    """Hard requirements this plan breaks (§8.1). Distinct from `infeasible_reasons`
+    about connections: one is "you would miss the conference", the other is "you
+    would miss the flight"."""
+    opportunities: list[StopoverOpportunity] = field(default_factory=list)
+    """Stopovers this routing makes possible but nobody has asked for yet (§8.3)."""
+    assumptions: AssumptionLog = field(default_factory=AssumptionLog)
+    """What had to be decided without being told (§10)."""
+
+    @property
+    def generalized_cost(self) -> Band:
+        return band_sum([line.amount for line in self.lines])
+
+    @property
+    def feasible(self) -> bool:
+        return not self.infeasible_reasons and not self.violations
+
+    @property
+    def money_full_one_off(self) -> Band:
+        """Out-of-pocket including un-amortized authorization costs."""
+        extra = sum(b.money_cost_full - b.money_cost for b in self.borders)
+        return self.money_total + extra
+
+    def by_kind(self, kind: CostKind) -> Band:
+        return band_sum([line.amount for line in self.lines if line.kind is kind])
+
+    def explain(self) -> str:
+        head = (
+            f"generalized {self.generalized_cost}  "
+            f"(money {self.money_total}"
+            + (
+                f", one-off {self.money_full_one_off}"
+                if self.money_full_one_off.mid != self.money_total.mid
+                else ""
+            )
+            + ")"
+        )
+        body = "\n".join(f"  {line}" for line in self.lines)
+        tail = ""
+        for violation in self.violations:
+            tail += f"\n  CONSTRAINT: {violation}"
+        for opportunity in self.opportunities:
+            tail += f"\n  OPPORTUNITY: {opportunity.question()}"
+        if self.infeasible_reasons:
+            tail += "\n  INFEASIBLE: " + "; ".join(self.infeasible_reasons)
+        return f"{head}\n{body}{tail}"
+
+
+# ── individual terms ──────────────────────────────────────────────────────────
+
+
+def _is_red_eye(segment: Segment, prefs: PreferenceProfile) -> bool:
+    hour = segment.local_departure_hour
+    return hour >= prefs.discomfort.red_eye_from_hour or hour < prefs.discomfort.red_eye_to_hour
+
+
+def _segment_time_cost(segment: Segment, prefs: PreferenceProfile) -> tuple[float, str]:
+    """Time only: hours you don't get back, at what an hour is worth.
+
+    The unpleasantness of a red-eye is *not* here. It is a fixed discomfort amount
+    (§8.2), because a broken night is a broken night whether the flight is two hours
+    or twelve — and because how much you mind it should not scale with your hourly
+    rate.
+    """
+    hours = segment.duration.total_seconds() / 3600
+    factor = prefs.time.in_flight_factor
+    note = f"{segment} {hours:.1f}h x{factor:g}"
+    return hours * factor * prefs.time.wage_rate_per_hour, note
+
+
+def _overnight_choice(hours: float, prefs: PreferenceProfile) -> tuple[float, str]:
+    """Price a night in transit as the cheaper of terminal or airport hotel."""
+    terminal = prefs.discomfort.cost(prefs.discomfort.night_in_terminal)
+    hotel = (
+        prefs.overnight.airport_hotel_cost
+        + prefs.overnight.hotel_transfer_hours * prefs.time.wage_rate_per_hour
+    )
+    if hotel < terminal:
+        return hotel, f"airport hotel assumed ({hours:.1f}h wait)"
+    return terminal, f"night in terminal assumed ({hours:.1f}h wait)"
+
+
+def _spans_night(connection: Connection, prefs: PreferenceProfile) -> bool:
+    """Does this gap eat a night?
+
+    Requires both length (a 2-hour wait at 23:00 is a wait, not a night) and
+    overlap with the overnight window, so a long daytime layover is not charged a
+    hotel and a 22:00–07:00 sit is not charged as ordinary dead time.
+    """
+    start, end = connection.arrive_segment.arrive, connection.depart_segment.depart
+    if (end - start).total_seconds() / 3600 < prefs.overnight.min_night_hours:
+        return False
+    hours_spanned = int((end - start).total_seconds() // 3600) + 1
+    return any(
+        (start.hour + offset) % 24 >= prefs.overnight.window_from_hour
+        or (start.hour + offset) % 24 < prefs.overnight.window_to_hour
+        for offset in range(hours_spanned)
+    )
+
+
+def _stay_nights(connection: Connection) -> int:
+    return max(
+        0,
+        (
+            connection.depart_segment.depart.date() - connection.arrive_segment.arrive.date()
+        ).days,
+    )
+
+
+def _requested_stopover(connection: Connection, ctx: PricingContext) -> StopoverRequest | None:
+    """Is this gap a wanted stopover, or a layover nobody asked for?
+
+    Three ways a stay can be wanted: the intent asked for it, the owner's standing
+    wishlist covers the place (`stopover_interest` — already an answered question),
+    or a question asked mid-search was answered yes, which arrives here as an entry
+    in `ctx.stopovers` with `source="asked"`.
+    """
+    place = connection.at_airport
+    nights = _stay_nights(connection)
+
+    request = ctx.stopovers.get(place)
+    if request is not None:
+        if request.min_nights <= nights <= request.max_nights:
+            return request
+        return None
+
+    # A wishlisted place needs no question: the owner priced it in advance. The
+    # length on offer becomes the ideal, since they valued the place and not a
+    # particular number of nights.
+    net = ctx.interest_in(place)
+    if net is not None and nights >= 1:
+        return StopoverRequest(
+            place=place,
+            min_nights=1,
+            ideal_nights=nights,
+            max_nights=nights,
+            net_at_ideal=net,
+            source="wishlist",
+        )
+    return None
+
+
+def _stopover_opportunity(
+    connection: Connection, ctx: PricingContext, *, as_wait_cost: float
+) -> StopoverOpportunity | None:
+    """Would this gap be worth offering as a stopover?
+
+    Only asked of gaps long enough to be a real stay: below
+    `stopover_candidate_min_hours` the question is noise. The break-even value is
+    computed from what the gap already costs as a layover, which is what makes the
+    question answerable — "worth €35 a night to you?" rather than "fancy Greece?".
+    """
+    if not ctx.offers_stopovers:
+        return None
+    hours = connection.gap_minutes / 60
+    if hours < ctx.candidate_min_hours:
+        return None
+
+    nights = max(1, _stay_nights(connection))
+    # Taking the stop replaces the wait cost with the stop's own net cost, so it wins
+    # whenever that net is below what waiting already costs.
+    return StopoverOpportunity(
+        place=connection.at_airport,
+        nights=nights,
+        hours=hours,
+        as_wait_cost=as_wait_cost,
+        net_ceiling=as_wait_cost,
+    )
+
+
+def _stopover_assumption(opportunity: StopoverOpportunity, plan_id: str) -> Assumption:
+    """The question, with both answers priced (§10)."""
+    nights = opportunity.nights
+    return Assumption(
+        key=f"stopover:{opportunity.place}:{nights}",
+        question=opportunity.question(),
+        options=[
+            Option(
+                label="stay in transit (default)",
+                value=0,
+                pros="nothing to arrange, no extra spending",
+                cons=f"{opportunity.hours:.0f}h of the trip spent in an airport, "
+                f"costed at {opportunity.as_wait_cost:.0f}",
+            ),
+            Option(
+                label=f"{nights} night(s) in {opportunity.place}",
+                value=nights,
+                pros="turns dead time into somewhere you wanted to be; beats "
+                f"waiting unless it costs more than {opportunity.net_ceiling:.0f} net",
+                cons="a hotel to pay for, bags to move, and the onward ticket "
+                "becomes a separate booking risk",
+            ),
+        ],
+        default=0,
+        blocking=False,
+        affects=[plan_id],
+    )
+
+
+def _constraints_broken_by_missing(
+    plan: TripPlan,
+    connection: Connection,
+    ctx: PricingContext,
+) -> list[HardConstraint]:
+    """Which hard requirements fail if *this* connection is missed.
+
+    The timing question, asked precisely: missing a connection pushes arrival by
+    `recovery_hours` (or overnight, if it was the day's last departure), and only the
+    constraints that then break are relevant to this connection. A self-transfer three
+    days before a conference breaks nothing; the same self-transfer the night before
+    breaks everything.
+    """
+    if not ctx.constraints:
+        return []
+
+    recovery = timedelta(
+        hours=(
+            ctx.prefs.delay.recovery_hours_overnight
+            if connection.onward_is_last_of_day
+            else ctx.prefs.delay.recovery_hours
+        )
+    )
+
+    broken: list[HardConstraint] = []
+    for constraint in ctx.constraints:
+        if constraint.kind is ConstraintKind.DEPART_AFTER:
+            continue  # a missed connection never makes you leave earlier
+        if constraint.kind is ConstraintKind.ARRIVE_BY and constraint.place is not None:
+            reached = [s.arrive for s in plan.segments if s.destination == constraint.place]
+            if not reached:
+                continue
+            would_arrive = reached[0] + recovery
+        else:
+            would_arrive = plan.arrive + recovery
+        # Only connections *before* the deadline can threaten it.
+        if connection.arrive_segment.arrive > constraint.when:
+            continue
+        if would_arrive > constraint.effective_deadline:
+            broken.append(constraint)
+    return broken
+
+
+def _stake_multiplier(plan: TripPlan, connection: Connection, ctx: PricingContext) -> float:
+    """How much extra cushion this connection deserves, given what it threatens (§8.9).
+
+    The honest replacement for the old business-mode buffer multiplier: cushion is
+    bought where something is actually at risk, not everywhere on a trip that happens
+    to contain a deadline.
+    """
+    broken = _constraints_broken_by_missing(plan, connection, ctx)
+    if not broken:
+        return 1.0
+    weight = max(c.stake_weight(ctx.prefs.constraints) for c in broken)
+    ceiling = ctx.prefs.constraints.stake_buffer_max_multiplier
+    return 1.0 + weight * (ceiling - 1.0)
+
+
+def _expected_violation_cost(
+    plan: TripPlan,
+    connection: Connection,
+    verdict: FeasibilityVerdict,
+    inbound_delay: DelayEstimate,
+    ctx: PricingContext,
+) -> float:
+    """P(this connection is missed) x what missing it would break.
+
+    "Definitely arrive by 20:00" cannot be checked against a schedule alone: a plan
+    that *intends* to land at 14:00 with a 15% chance of arriving tomorrow satisfies
+    the timetable and fails the requirement. Stakes turn that probability into money,
+    so a fragile plan loses on the objective instead of needing a flag to forbid it.
+    """
+    broken = _constraints_broken_by_missing(plan, connection, ctx)
+    if not broken:
+        return 0.0
+
+    cushion = verdict.slack_minutes + verdict.breakdown.delay_allowance_minutes
+    probability = p_miss(inbound_delay, cushion)
+    if probability <= 0:
+        return 0.0
+    return probability * sum(c.cost_of_missing(ctx.prefs.constraints) for c in broken)
+
+
+def _segments_with_leg(plan: TripPlan) -> list[tuple[int, Segment]]:
+    """Every segment, tagged with its leg index across the whole plan.
+
+    Leg boundaries are where valuations may change: the way to something and the way
+    home are different legs and an hour on each can be worth different amounts.
+    """
+    out: list[tuple[int, Segment]] = []
+    leg_index = 0
+    for offer in plan.offers:
+        for leg in offer.legs:
+            for segment in leg.segments:
+                out.append((leg_index, segment))
+            leg_index += 1
+    return out
+
+
+def price_plan(plan: TripPlan, ctx: PricingContext) -> PlanCost:
+    """Price a plan into a generalized cost with a full itemization."""
+    prefs = ctx.prefs
+    wage = prefs.time.wage_rate_per_hour
+    lines: list[CostLine] = []
+    risks: list[RiskAnnotation] = []
+    discomfort: list[tuple[float, str]] = []
+    expected_misconnect = 0.0
+    expected_violation = 0.0
+    infeasible: list[str] = []
+    verdicts: list[FeasibilityVerdict] = []
+    party_borders: list[PartyBorder] = []
+    notes: list[str] = []
+    opportunities: list[StopoverOpportunity] = []
+    assumptions = AssumptionLog()
+
+    # ── money ────────────────────────────────────────────────────────────────
+    fares = plan.money_out_of_pocket
+    if fares is None:
+        infeasible.append(
+            "an offer has no reference rate — uncomparable, excluded from ranking"
+        )
+        money = Band.zero()
+    else:
+        money = Band.exact(fares)
+        lines.append(
+            CostLine(CostKind.FARE, money, f"{len(plan.offers)} ticket(s), normalized")
+        )
+    if ctx.ancillary_estimate is not None:
+        lines.append(
+            CostLine(
+                CostKind.ANCILLARY,
+                ctx.ancillary_estimate,
+                f"baggage under {ctx.baggage_profile}",
+            )
+        )
+        money = money + ctx.ancillary_estimate
+
+    # ── time in the air, at each leg's own valuation ─────────────────────────
+    for leg_index, segment in _segments_with_leg(plan):
+        leg_prefs = ctx.prefs_for_leg(leg_index)
+        cost, note = _segment_time_cost(segment, leg_prefs)
+        if leg_prefs is not prefs:
+            note += f" [{leg_prefs.label or f'leg {leg_index}'}]"
+        lines.append(CostLine(CostKind.TRAVEL_TIME, Band.exact(cost), note))
+
+    for _, segment in _segments_with_leg(plan):
+        if _is_red_eye(segment, prefs):
+            discomfort.append(
+                (
+                    prefs.discomfort.cost(prefs.discomfort.red_eye_per_flight),
+                    f"{segment.carrier}{segment.flight_number} departs "
+                    f"{segment.local_departure_hour:02d}:xx — a night lost",
+                )
+            )
+
+    # ── expected delay ───────────────────────────────────────────────────────
+    for leg_index, segment in _segments_with_leg(plan):
+        leg_prefs = ctx.prefs_for_leg(leg_index)
+        wage = leg_prefs.time.wage_rate_per_hour
+        estimate = ctx.delay_for(segment)
+        cost = estimate.mean_min / 60 * wage * leg_prefs.time.layover_factor
+        lines.append(
+            CostLine(
+                CostKind.EXPECTED_DELAY,
+                Band.exact(cost),
+                f"{segment.carrier}{segment.flight_number} "
+                f"{segment.local_departure_hour:02d}:xx dep, "
+                f"{estimate.mean_min:.0f}m expected slip ({estimate.source})",
+            )
+        )
+
+    # ── connections: waits, stopovers, borders, feasibility, risk ────────────
+
+    for connection in plan.connections():
+        if connection.at_airport in ctx.destinations:
+            # The stay at the destination is a stop like any other (§8.3) — it just
+            # happens to be the point of the trip. What it is *not* is a transfer:
+            # there is no misconnect to fear (missing your own return flight is a
+            # different problem) and no self-transfer hassle in buying the two
+            # directions separately, so none of the machinery below applies.
+            if not connection.within_offer:
+                # The two directions were bought apart. Not a misconnect — nothing
+                # connects here but the stay — so it is annotated, not priced: the
+                # exposure is that the bookings fail independently, and a cancelled
+                # outbound leaves a return that is still yours to deal with. Pricing
+                # it would need a cancellation prior nobody has (§8.7).
+                risks.append(
+                    RiskAnnotation(
+                        kind=RiskKind.SEPARATE_PNR,
+                        detail=(
+                            f"{connection.at_airport}: outbound and return bought "
+                            "separately — one cancellation does not release the other, "
+                            "and bags are paid for twice"
+                        ),
+                    )
+                )
+            stay = ctx.stopovers.get(connection.at_airport)
+            if stay is not None:
+                nights = max(0, _stay_nights(connection))
+                net = stay.cost_of(nights, scale=ctx.stopover_length_scale)
+                if net:
+                    lines.append(
+                        CostLine(
+                            CostKind.STOPOVER,
+                            Band.exact(net),
+                            f"{connection.at_airport} {nights}n "
+                            f"vs ideal {stay.bounds().ideal:g}n",
+                        )
+                    )
+            continue
+        stay_hours = connection.gap_minutes / 60
+        inbound_delay = ctx.delay_for(connection.arrive_segment)
+        country = ctx.country_of(connection.at_airport)
+
+        border: PartyBorder | None = None
+        border_minutes = 0.0
+        entry_required = False
+        if country and ctx.regimes is not None:
+            border = borders_mod.resolve_party(
+                ctx.party,
+                country,
+                table=ctx.regimes,
+                departure=connection.arrive_segment.arrive.date(),
+                wage_rate_per_hour=wage,
+            )
+            party_borders.append(border)
+            border_minutes = border.added_time_min
+            entry_required = border.regime is Regime.ENTRY_REQUIRED
+            if border_minutes:
+                lines.append(
+                    CostLine(
+                        CostKind.BORDER,
+                        Band.exact(border_minutes / 60 * wage),
+                        f"{border.country} {border.regime}: {border_minutes:.0f}m "
+                        f"(party maximum)",
+                    )
+                )
+            for per in border.per_traveler:
+                if per.money_cost:
+                    lines.append(
+                        CostLine(
+                            CostKind.BORDER,
+                            Band.exact(per.money_cost),
+                            per.note,
+                            traveler_id=per.traveler_id,
+                        )
+                    )
+                if per.authorization_status.value == "obtainable":
+                    risks.append(
+                        RiskAnnotation(
+                            kind=RiskKind.AUTHORIZATION_PENDING,
+                            detail=per.note,
+                            traveler_id=per.traveler_id,
+                        )
+                    )
+            if not border.feasible:
+                infeasible.extend(border.blocking_notes)
+            if border.regime is Regime.UNKNOWN:
+                risks.append(
+                    RiskAnnotation(
+                        kind=RiskKind.UNKNOWN_TRANSIT_REGIME,
+                        detail=(
+                            f"{country}: transit regime not in the table — ask, don't assume"
+                        ),
+                    )
+                )
+
+        request = _requested_stopover(connection, ctx)
+
+        # Feasibility comes before pricing: an infeasible connection is not an
+        # expensive plan, it is not a plan.
+        stake_multiplier = _stake_multiplier(plan, connection, ctx)
+        verdict = assess(
+            connection,
+            prefs.feasibility,
+            checked_bag=ctx.checked_bag,
+            inbound_delay=inbound_delay,
+            border_minutes=border_minutes,
+            entry_required=entry_required,
+            stopover_requested=request is not None,
+            stake_multiplier=stake_multiplier,
+        )
+        verdicts.append(verdict)
+        if not verdict.feasible:
+            infeasible.append(f"{connection}: {verdict.reason}")
+
+        if request is not None:
+            nights = max(
+                1,
+                (
+                    connection.depart_segment.depart.date()
+                    - connection.arrive_segment.arrive.date()
+                ).days,
+            )
+            # One line, one function: what the stay is worth plus how far its length
+            # is from the one that was wanted (§8.3). No per-night rate anywhere.
+            net = request.cost_of(nights, scale=ctx.stopover_length_scale)
+            wanted = request.bounds().ideal
+            note = f"{connection.at_airport} {nights}n"
+            if nights != wanted:
+                note += f" vs ideal {wanted:g}n"
+            if request.net_at_ideal:
+                worth = -request.net_at_ideal
+                note += f" (worth {worth:.0f} at best)" if worth > 0 else ""
+            if net:
+                lines.append(CostLine(CostKind.STOPOVER, Band.exact(net), note))
+            # Requested stopover hours leave the time account entirely (§8.3).
+        else:
+            wait_factor = prefs.time.layover_factor
+            note = f"{connection.at_airport} {stay_hours:.1f}h wait"
+            if connection.gap_minutes < prefs.discomfort.tight_connection_minutes:
+                # The stress of running for a gate is a fixed unpleasantness, not a
+                # multiple of 45 minutes — and it should not grow because your hourly
+                # rate did.
+                discomfort.append(
+                    (
+                        prefs.discomfort.cost(prefs.discomfort.tight_connection),
+                        f"tight connection at {connection.at_airport} "
+                        f"({connection.gap_minutes:.0f}m)",
+                    )
+                )
+
+            if _spans_night(connection, prefs):
+                # Per night, per traveller: two people stuck for two nights is four
+                # bad nights, not one.
+                nights_stuck = max(1, _stay_nights(connection))
+                per_night, overnight_note = _overnight_choice(stay_hours, prefs)
+                wait_cost = per_night * nights_stuck * ctx.party.size
+                lines.append(
+                    CostLine(
+                        CostKind.INVOLUNTARY_WAIT,
+                        Band.exact(wait_cost),
+                        f"{connection.at_airport}: {overnight_note}, "
+                        f"{nights_stuck} night(s) x{ctx.party.size} traveller(s)",
+                    )
+                )
+                opportunity = _stopover_opportunity(connection, ctx, as_wait_cost=wait_cost)
+                if opportunity is not None:
+                    opportunities.append(opportunity)
+                    assumptions.add(_stopover_assumption(opportunity, plan.plan_id))
+            else:
+                dead_time = stay_hours * wait_factor * wage
+                total_wait_cost = 0.0
+                lounge_money = 0.0
+                lounge_notes: list[str] = []
+                for traveler in ctx.party.travelers:
+                    decision = lounge_mod.decide(
+                        traveler,
+                        wait_hours=stay_hours,
+                        dead_time_cost=dead_time,
+                        has_lounge_here=connection.at_airport in ctx.lounge_airports,
+                        prefs=prefs.lounge,
+                        policy=prefs.lounge.use,
+                    )
+                    total_wait_cost += dead_time * decision.wait_factor
+                    lounge_money += decision.cost
+                    if decision.used:
+                        lounge_notes.append(f"{traveler.id}: {decision.note}")
+                lines.append(
+                    CostLine(
+                        CostKind.INVOLUNTARY_WAIT,
+                        Band.exact(total_wait_cost),
+                        f"{note} x{ctx.party.size} traveller(s)",
+                    )
+                )
+                if lounge_money or lounge_notes:
+                    lines.append(
+                        CostLine(
+                            CostKind.LOUNGE,
+                            Band.exact(lounge_money),
+                            "; ".join(lounge_notes) or "lounge entry",
+                        )
+                    )
+                opportunity = _stopover_opportunity(
+                    connection, ctx, as_wait_cost=total_wait_cost + lounge_money
+                )
+                if opportunity is not None:
+                    opportunities.append(opportunity)
+                    assumptions.add(_stopover_assumption(opportunity, plan.plan_id))
+
+        # Ground transfer for an airport change — free of hassle only when the
+        # stopover was wanted, because then you were leaving the airport anyway.
+        if connection.airport_change:
+            transfer_money = prefs.ground.default_metro_transfer_cost * ctx.party.size
+            transfer_time = (
+                prefs.ground.default_metro_transfer_hours
+                * prefs.time.ground_transfer_factor
+                * wage
+            )
+            if request is not None:
+                lines.append(
+                    CostLine(
+                        CostKind.GROUND_TRANSFER,
+                        Band.exact(transfer_money),
+                        f"{connection.arrive_segment.destination}->"
+                        f"{connection.depart_segment.origin} ground ticket "
+                        f"(stopover requested: part of the trip, no hassle premium)",
+                    )
+                )
+            else:
+                lines.append(
+                    CostLine(
+                        CostKind.GROUND_TRANSFER,
+                        Band.exact(transfer_money + transfer_time),
+                        f"{connection.arrive_segment.destination}->"
+                        f"{connection.depart_segment.origin} transfer + time",
+                    )
+                )
+                discomfort.append(
+                    (
+                        prefs.discomfort.cost(prefs.discomfort.airport_change),
+                        f"airport change {connection.arrive_segment.destination}->"
+                        f"{connection.depart_segment.origin}",
+                    )
+                )
+                risks.append(
+                    RiskAnnotation(
+                        kind=RiskKind.AIRPORT_CHANGE,
+                        detail=f"{connection.arrive_segment.destination} to "
+                        f"{connection.depart_segment.origin} on separate tickets",
+                    )
+                )
+
+        # ── unprotected connections: unpleasantness, then arithmetic ──────────
+        if connection.is_protected:
+            # A protected connection can still be missed, and if it stands before a
+            # hard constraint that matters — the airline rebooks you, but not
+            # necessarily in time for the conference.
+            expected_violation += _expected_violation_cost(
+                plan, connection, verdict, inbound_delay, ctx
+            )
+            continue
+
+        if connection.protection is Protection.GUARANTEED_SELF_TRANSFER:
+            discomfort.append(
+                (
+                    prefs.discomfort.cost(prefs.discomfort.third_party_guarantee),
+                    f"{connection.at_airport}: guaranteed self-transfer",
+                )
+            )
+            risks.append(
+                RiskAnnotation(
+                    kind=RiskKind.THIRD_PARTY_GUARANTEE,
+                    detail=f"{connection.at_airport}: separate tickets, aggregator guarantee",
+                )
+            )
+        else:
+            discomfort.append(
+                (
+                    prefs.discomfort.cost(
+                        prefs.discomfort.self_transfer + prefs.discomfort.separate_ticket
+                    ),
+                    f"{connection.at_airport}: self-transfer on separate tickets",
+                )
+            )
+            risks.append(
+                RiskAnnotation(
+                    kind=RiskKind.SEPARATE_PNR,
+                    detail=f"{connection.at_airport}: self-transfer, no protection",
+                )
+            )
+        if entry_required:
+            discomfort.append(
+                (
+                    prefs.discomfort.cost(prefs.discomfort.border_entry_exit),
+                    f"{connection.at_airport}: border inside a self-transfer",
+                )
+            )
+            risks.append(
+                RiskAnnotation(
+                    kind=RiskKind.ENTRY_EXIT_TRANSIT,
+                    detail=f"{connection.at_airport}: border in the middle of a self-transfer",
+                )
+            )
+        if ctx.checked_bag:
+            discomfort.append(
+                (
+                    prefs.discomfort.cost(prefs.discomfort.bag_recheck),
+                    f"{connection.at_airport}: claim and re-check the bag",
+                )
+            )
+
+        # Total absorbing time: slack beyond the buffer plus the allowance the buffer
+        # already contains (§8.9) — see p_miss on why bare slack is wrong.
+        cushion = verdict.slack_minutes + verdict.breakdown.delay_allowance_minutes
+        probability = p_miss(inbound_delay, cushion)
+        replacement = prefs.delay.misconnect_replacement_cost * ctx.party.size
+        consequence = replacement
+        if connection.onward_is_last_of_day:
+            overnight_cost, _ = _overnight_choice(8.0, prefs)
+            consequence += overnight_cost * ctx.party.size + 24 * 0.5 * wage
+        expected_misconnect += probability * consequence
+        expected_violation += _expected_violation_cost(
+            plan, connection, verdict, inbound_delay, ctx
+        )
+        notes.append(
+            f"{connection.at_airport}: P(miss)={probability:.0%} on "
+            f"{cushion:.0f}m cushion, consequence ~{consequence:.0f}"
+        )
+
+    # ── flexibility ──────────────────────────────────────────────────────────
+    moments = align(plan, [stop.place for stop in ctx.journey])
+    for stop, actual in zip(ctx.journey, moments, strict=False):
+        for verb, when, ask in (
+            ("into", actual.arrive, stop.arrive),
+            ("out of", actual.depart, stop.depart),
+        ):
+            if when is None or ask is None:
+                continue
+            priced = ask(when)
+            if priced is None or not priced.amount:
+                continue
+            stamp = f"{when:%Y-%m-%d %H:%M}" if priced.timed else f"{when.date()}"
+            lines.append(
+                CostLine(
+                    CostKind.DATE_FLEXIBILITY,
+                    Band.exact(priced.amount),
+                    f"{verb} {stop.place} {stamp}",
+                )
+            )
+    if not ctx.journey and plan.segments:
+        # No journey stated: the older single-window path, outbound departure only.
+        first = plan.segments[0].depart
+        priced = ctx.departure_cost(first) if ctx.departure_cost else None
+        cost = priced.amount if priced else ctx.date_costs.get(first.date())
+        if cost:
+            stamp = f"{first:%Y-%m-%d %H:%M}" if priced and priced.timed else f"{first.date()}"
+            lines.append(
+                CostLine(CostKind.DATE_FLEXIBILITY, Band.exact(cost), f"leaves {stamp}")
+            )
+    # Trip length is only defined for a plan that comes home. A one-way — or the
+    # outbound half of a round trip, which is what a Google Flights row is — has no
+    # duration to deviate from, and charging one would punish every candidate
+    # identically while looking like a real cost.
+    returns_home = plan.segments[-1].destination == plan.segments[0].origin
+    if returns_home and (ctx.duration_cost or ctx.preferred_nights is not None):
+        nights = (plan.arrive.date() - plan.depart.date()).days
+        cost = ctx.duration_cost(nights) if ctx.duration_cost else None
+        note = f"{nights}n vs the stated length"
+        if cost is None and ctx.preferred_nights is not None:
+            # No window, only a preferred length: the standing per-night rate, which
+            # is asymmetric because an extra day away and a day short of the trip you
+            # planned are different kinds of loss.
+            cost = prefs.flexibility.duration_cost(nights, ctx.preferred_nights)
+            direction = "away longer" if nights > ctx.preferred_nights else "shorter"
+            note = f"{nights}n vs preferred {ctx.preferred_nights}n ({direction})"
+        if cost:
+            lines.append(CostLine(CostKind.DURATION_DEVIATION, Band.exact(cost), note))
+
+    # ── hard constraints: checked, not priced (§8.1) ─────────────────────────
+    violations = check_constraints(plan, ctx.constraints)
+
+    # ── discomfort: what the trip costs in unpleasantness (§8.2) ─────────────
+    if discomfort:
+        total_discomfort = sum(amount for amount, _ in discomfort)
+        lines.append(
+            CostLine(
+                CostKind.DISCOMFORT,
+                Band.exact(total_discomfort * ctx.party.size),
+                "; ".join(note for _, note in discomfort)
+                + (f" (x{ctx.party.size} travellers)" if ctx.party.size > 1 else "")
+                + (
+                    f" [comfort scale {prefs.discomfort.scale:g}]"
+                    if prefs.discomfort.scale != 1.0
+                    else ""
+                ),
+            )
+        )
+
+    # ── risk: probabilities times consequences, nothing else (§8.7) ──────────
+    # No hassle terms and no floor: unpleasantness is priced above as discomfort, and
+    # the stakes of a hard constraint are what make a risky plan lose.
+    if expected_misconnect or expected_violation:
+        detail = f"expected misconnection {expected_misconnect:.0f}"
+        if expected_violation:
+            detail += f" + expected constraint violation {expected_violation:.0f}"
+        lines.append(
+            CostLine(
+                CostKind.RISK_PREMIUM,
+                Band.exact(expected_misconnect + expected_violation),
+                detail,
+            )
+        )
+
+    return PlanCost(
+        lines=lines,
+        money_total=money,
+        risks=risks,
+        infeasible_reasons=infeasible,
+        verdicts=verdicts,
+        borders=party_borders,
+        notes=notes,
+        opportunities=opportunities,
+        assumptions=assumptions,
+        violations=violations,
+    )
+
+
+def breakeven_wage_rate(
+    plan_a: TripPlan,
+    plan_b: TripPlan,
+    ctx: PricingContext,
+    *,
+    low: float = 0.0,
+    high: float = 500.0,
+    tolerance: float = 0.05,
+) -> float | None:
+    """The hourly rate at which two plans swap places (DESIGN §8.8).
+
+    Because `wage_rate_per_hour` is a guess, every report states this: "#1 and #2
+    trade places if your time is worth less than €4.50/h" tells the owner whether
+    a ranking is a finding or an artifact. Returns None when no crossing exists in
+    the range — the ordering does not depend on the rate at all.
+    """
+
+    def delta(rate: float) -> float:
+        probe = replace(
+            ctx, prefs=ctx.prefs.with_overrides({"time": {"wage_rate_per_hour": rate}})
+        )
+        return (
+            price_plan(plan_a, probe).generalized_cost.mid
+            - price_plan(plan_b, probe).generalized_cost.mid
+        )
+
+    low_delta, high_delta = delta(low), delta(high)
+    if (low_delta > 0) == (high_delta > 0):
+        return None
+    for _ in range(60):
+        mid = (low + high) / 2
+        if high - low < tolerance:
+            return round(mid, 2)
+        if (delta(mid) > 0) == (low_delta > 0):
+            low = mid
+        else:
+            high = mid
+    return round((low + high) / 2, 2)