layover 0.1.0.dev0__py3-none-any.whl

layover/intent.py

@@ -0,0 +1,1016 @@
+"""TravelIntent: what the owner asked for (DESIGN §4).
+
+A boring, validated structure. Flexibility lives in the date windows, the stopover
+specs and the solver — not in a clever query language. The LLM front end is the
+"flexible expression" layer; this is its compile target.
+
+Two things this module is careful about:
+
+* **Date windows compile to prices.** `min`/`ideal`/`max` is sugar for a map from
+  moment to what departing then costs (§8.4). The map is the real thing, because
+  flexibility is neither linear nor symmetric; the default curve is quadratic in the
+  distance from `ideal`, so the first hour off target is nearly free and the last one
+  before the hard edge is not.
+* **Hard requirements are not preferences.** `[[constraints]]` entries are checked
+  and never priced, and each carries the stakes of missing it (§8.1). Nothing here
+  says what *kind* of trip this is, because there is no such thing.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from datetime import date, datetime, time, timedelta
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, PrivateAttr, model_validator
+
+from layover.cost import curve
+from layover.cost.constraints import ConstraintKind, Criticality, HardConstraint
+from layover.cost.generalized import DateCost
+from layover.models import BaggageProfile, Cabin, TripShape
+
+MAX_DATE_COMBINATIONS = 4096
+"""Where enumerating the search space stops and says so (§6)."""
+
+DEFAULT_COST_AT_TOLERANCE = 60.0
+"""What the edge of a date window costs before anyone says otherwise.
+
+The owner's standing answer lives in `preferences.toml`
+(`[flexibility] date_cost_at_tolerance`) and reaches a window through
+`with_default_scale`; a single trip overrides both by pricing its own window. This
+constant is only what holds until preferences are loaded — deliberately not free and
+not enormous, since the edge of what is possible should be worth avoiding without
+being able to outvote a real difference in fare."""
+
+NOON = time(12, 0)
+"""Where a bare `ideal` date sits. A day named without a time means the day, and its
+middle is the only unbiased reading of it."""
+
+
+def _as_date(value: date | datetime) -> date:
+    return value.date() if isinstance(value, datetime) else value
+
+
+def _at(value: date | datetime, clock: time, tz=None) -> datetime:
+    """A datetime as given, or the named date at this time of day."""
+    if isinstance(value, datetime):
+        return value if value.tzinfo or tz is None else value.replace(tzinfo=tz)
+    return datetime.combine(value, clock, tzinfo=tz)
+
+
+def _floor(value: date | datetime, tz=None) -> datetime:
+    return _at(value, time.min, tz)
+
+
+def _ceiling(value: date | datetime, tz=None) -> datetime:
+    return _at(value, time.max, tz)
+
+
+class Strict(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class PlaceSpec(Strict):
+    code: str = Field(min_length=3, max_length=4)
+    radius_km: float | None = None
+    """Nearby-airport search radius, honoured by oracles that support it."""
+
+    @classmethod
+    def parse(cls, value: str | dict[str, Any]) -> PlaceSpec:
+        if isinstance(value, str):
+            return cls(code=value.upper())
+        return cls.model_validate({**value, "code": str(value["code"]).upper()})
+
+
+class TimeOfDayWindow(Strict):
+    """The same window, written as clock times — a preference that recurs daily.
+
+    "Land by 16:00, never after 01:00" is not a statement about one moment. It is true
+    of whichever day the flight lands on, and an absolute window cannot say it: pinned
+    to a date, it would rule out every departure except one, and widened to cover the
+    whole departure range it would stop meaning anything at all.
+
+    So the axis is the clock. Distances are hours from the ideal, wrapped into ±12, and
+    the curve is the one in `cost.curve` — which is why "ideally 16:00, no later than
+    01:00" is nine hours of tolerance rather than a contradiction. Midnight is not a
+    boundary here; it is just another hour.
+    """
+
+    min: time | None = None
+    ideal: time | None = None
+    max: time | None = None
+    cost_at_tolerance: float | None = None
+    tolerance_hours: float | None = None
+
+    @model_validator(mode="after")
+    def _check(self) -> TimeOfDayWindow:
+        if all(v is None for v in (self.min, self.ideal, self.max)):
+            raise ValueError("a time-of-day window needs min, ideal or max")
+        if self.ideal is None and self.min is not None and self.max is not None:
+            span = _wrap(_hours(self.max) - _hours(self.min))
+            middle = (_hours(self.min) + span / 2) % 24
+            self.ideal = time(int(middle), int(middle % 1 * 60))
+        elif self.ideal is None:
+            self.ideal = self.min or self.max
+        _ = self.bounds  # fail now, not at the first flight that hits it
+        return self
+
+    @property
+    def bounds(self) -> curve.Bounds:
+        """Hours from the ideal: negative early, positive late, wrapped through midnight."""
+        low = _wrap(_hours(self.min) - _hours(self.ideal)) if self.min else None
+        high = _wrap(_hours(self.max) - _hours(self.ideal)) if self.max else None
+        if low is not None and low > 0:
+            raise ValueError(f"min {self.min} is later in the day than ideal {self.ideal}")
+        if high is not None and high < 0:
+            raise ValueError(f"max {self.max} is earlier in the day than ideal {self.ideal}")
+        return curve.resolve(low, 0.0, high)
+
+    def cost_of(self, when: datetime) -> float | None:
+        scale = self.cost_at_tolerance
+        if scale is None:
+            scale = DEFAULT_COST_AT_TOLERANCE
+        offset = _wrap(_hours(when.time()) - _hours(self.ideal))
+        return curve.cost(offset, self.bounds, scale=scale, tolerance=self.tolerance_hours)
+
+    def priced(self, when: datetime) -> DateCost | None:
+        cost = self.cost_of(when)
+        return None if cost is None else DateCost(cost, timed=True)
+
+    def with_default_scale(self, scale: float) -> TimeOfDayWindow:
+        if self.cost_at_tolerance is not None:
+            return self
+        return self.model_copy(update={"cost_at_tolerance": scale})
+
+    def describe(self) -> str:
+        bounds = self.bounds
+        return (
+            f"{self.min or '—'}..{self.max or '—'} daily, ideally {self.ideal} "
+            f"({bounds.low:+.0f}h/{bounds.high:+.0f}h tolerance)"
+        )
+
+
+def _hours(value: time) -> float:
+    return value.hour + value.minute / 60 + value.second / 3600
+
+
+def _wrap(hours: float) -> float:
+    """An hour difference as the shortest way round the clock: (-12, +12]."""
+    return (hours + 12) % 24 - 12
+
+
+class DateWindow(Strict):
+    """When the flight may go, when it ideally goes, and what missing that costs.
+
+    Three values describe a window — `min`, `ideal`, `max` — and the cost of every
+    other moment falls out of them. `min` and `max` are the hard edges: outside them
+    there is no window, and the search never asks. `ideal` is the moment that costs
+    nothing. Any two of the three are enough, and the missing one is inferred by the
+    rules in `cost.curve.resolve` — two bounds and no ideal means the middle, one
+    bound and an ideal mirrors the stated side. In between, the default is quadratic
+    in the distance from `ideal`, measured in units of a tolerance breadth:
+
+        cost = cost_at_tolerance × ((when − ideal) / tolerance)²
+
+    Quadratic rather than linear because that is how the preference actually behaves:
+    an hour or a day either side of the target is nearly free (the curve is flat at
+    its bottom), while the last day before the hard edge is expensive. A flat rate per
+    day says the opposite — that the first day and the last day hurt equally — which is
+    the shape that made `deviation_cost_per_day` unsatisfying to write.
+
+    The tolerance defaults to the distance from `ideal` to the bound *on that side*,
+    which makes two useful things true at once: the cost at either edge is exactly
+    `cost_at_tolerance`, and asymmetry needs no extra syntax. An `ideal` sitting close to
+    `min` and far from `max` is a statement that leaving early is punished sooner than
+    leaving late. State `tolerance_days` (or `tolerance_hours`) to decouple the two:
+    a breadth smaller than the distance to the bound makes the edges cost more than
+    `cost_at_tolerance`, a larger one makes the whole window shallower.
+
+    **Times, not just dates.** Any of the three may carry a time of day, and then the
+    whole window works in hours: "ideally airborne by 09:00, not before 06:00, not
+    after 14:00" is one window, not a date plus a separate preference. A bare date
+    means the whole day (`min` from 00:00, `max` to 23:59, `ideal` at noon). The
+    compiled per-date map then holds the *best* cost obtainable on each day, which is
+    what the date-pair enumeration and the oracle window need; `cost_of(datetime)`
+    gives the exact price of an actual departure.
+
+    **Departure and arrival are two windows, not one.** The window itself is about
+    when the flight *leaves*; `[date_windows.outbound.arrive]` nests the same shape
+    for when it lands. Together with the trip length (`[duration]`) that makes three
+    quantities of which any two determine the third, so stating two is normal and
+    stating all three is allowed — each is priced on its own, and the report shows
+    which ones spoke.
+
+    **Or say it by hand.** `costs = { 2026-11-05 = 30, ... }` prices named days
+    outright, overriding the curve and free to name days outside it. `blocked = [...]`
+    removes days entirely — an appointment is not a price. Both are there because no
+    curve fits every trip, and the map from moment to money is the real model; the
+    three values above are the shorthand that usually fills it in.
+    """
+
+    min: date | datetime | None = None
+    ideal: date | datetime | None = None
+    max: date | datetime | None = None
+    cost_at_tolerance: float | None = None
+    """Money charged at the tolerance breadth away from `ideal` — by default, at the
+    window's own edge. Per trip rather than per person: how much a day matters varies
+    far more between trips than the wage rate does."""
+    tolerance_days: float | None = None
+    tolerance_hours: float | None = None
+    """Breadth of the quadratic. Defaults to the distance from `ideal` to each bound."""
+
+    arrive: DateWindow | TimeOfDayWindow | None = None
+    """When this direction should *land*, in exactly the same shape.
+
+    A separate preference from the departure and often the one that is actually felt:
+    nobody minds leaving at 06:00 as much as they mind landing at 02:00.
+
+    Written with dates it is one absolute window; written with bare clock times
+    (`ideal = 16:00:00`) it is a `TimeOfDayWindow` and applies to whichever day the
+    flight lands — which is what an arrival preference usually means when the
+    departure itself is still free to move."""
+
+    costs: dict[date, float] = Field(default_factory=dict)
+    """Explicit per-day prices; these override whatever the curve computed."""
+    blocked: list[date] = Field(default_factory=list)
+    preferred: date | None = None
+    """Output: the cheapest day in the compiled window."""
+
+    # Older, flatter shorthand, still honoured: a fixed price per day of deviation.
+    center: date | None = None
+    plus_minus_days: int | None = None
+    deviation_cost_per_day: float | None = None
+    earlier_cost_per_day: float | None = None
+    """Asymmetry: leaving early and coming back late are rarely the same price."""
+    later_cost_per_day: float | None = None
+
+    _declared: dict[str, Any] = PrivateAttr(default_factory=dict)
+    """The window exactly as it was written, kept so it can be recompiled.
+
+    Validation turns the shorthand into a map, which is one-way: `costs` afterwards
+    holds the *result* of the curve, and feeding that back in would make it explicit
+    and freeze it. Resolving a default scale from preferences means compiling again
+    from what the owner actually wrote."""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _pick_arrival_shape(cls, data: Any) -> Any:
+        """Clock times mean a daily window; dates mean an absolute one.
+
+        Decided here rather than left to union coercion, because the two models would
+        otherwise both half-accept the same input and the loser would be whichever
+        pydantic tried first.
+        """
+        if not isinstance(data, dict):
+            return data
+        arrive = data.get("arrive")
+        if isinstance(arrive, dict):
+            stated = [arrive.get(k) for k in ("min", "ideal", "max")]
+            if any(isinstance(v, time) and not isinstance(v, datetime) for v in stated):
+                data = {**data, "arrive": TimeOfDayWindow.model_validate(arrive)}
+        return data
+
+    @model_validator(mode="after")
+    def _expand(self) -> DateWindow:
+        self._declared = {
+            name: getattr(self, name)
+            for name in (
+                "min",
+                "ideal",
+                "max",
+                "arrive",
+                "cost_at_tolerance",
+                "tolerance_days",
+                "tolerance_hours",
+                "costs",
+                "blocked",
+                "preferred",
+                "center",
+                "plus_minus_days",
+                "deviation_cost_per_day",
+                "earlier_cost_per_day",
+                "later_cost_per_day",
+            )
+        }
+        if isinstance(self.arrive, DateWindow) and self.arrive.arrive is not None:
+            raise ValueError("an arrival window has no arrival of its own")
+        if not self._resolve_bounds() and not self.costs:
+            raise ValueError("a date window needs min, ideal or max — or `costs`")
+
+        computed: dict[date, float] = {}
+        if self.ideal is not None:
+            day = _as_date(self.min)
+            while day <= _as_date(self.max):
+                computed[day] = self._best_cost_on(day)
+                day += timedelta(days=1)
+
+        computed.update(self.costs)  # a stated price wins over any curve
+        for day in self.blocked:
+            computed.pop(day, None)  # unavailable, not merely expensive
+        if not computed:
+            raise ValueError("every date in this window is blocked")
+
+        # Costs are relative to the best day and never negative; a window written as a
+        # list of absolute prices is rebased only if it would otherwise go below zero.
+        floor = min(0.0, min(computed.values()))
+        self.costs = {day: round(cost - floor, 6) for day, cost in computed.items()}
+        if self.preferred is None or self.preferred not in self.costs:
+            self.preferred = min(self.costs, key=lambda d: (self.costs[d], d))
+        return self
+
+    def _resolve_bounds(self) -> bool:
+        """Fill in whichever of min/ideal/max were left out. False if none were given.
+
+        The rules are `cost.curve.resolve`'s, done in calendar arithmetic: mirroring
+        happens in whole days for a window that names no times, and in real moments for
+        one that does. A dateless window mirrored through midnight would land a day off,
+        which is the kind of quiet error a date window must not make.
+        """
+        ideal = self.ideal or self.center or self.preferred
+        low, high = self.min, self.max
+        if ideal is None and low is None and high is None:
+            return False
+
+        timed = any(isinstance(v, datetime) for v in (low, ideal, high))
+        if ideal is None:
+            if low is not None and high is not None:
+                span = _ceiling(high) - _floor(low)
+                middle = _floor(low) + span / 2
+                ideal = middle if timed else middle.date()
+            else:
+                ideal = low if low is not None else high
+        if low is None and high is None:
+            # Nothing but an ideal: `plus_minus_days` if it was given, else a window
+            # of exactly one day, which is a legitimate thing to want.
+            span = timedelta(days=self.plus_minus_days or 0)
+            low = ideal - span if timed else _as_date(ideal) - span
+            high = ideal + span if timed else _as_date(ideal) + span
+        if low is None:
+            low = (
+                _at(ideal, NOON) - (_ceiling(high) - _at(ideal, NOON))
+                if timed
+                else _as_date(ideal) - (_as_date(high) - _as_date(ideal))
+            )
+        if high is None:
+            high = (
+                _at(ideal, NOON) + (_at(ideal, NOON) - _floor(low))
+                if timed
+                else _as_date(ideal) + (_as_date(ideal) - _as_date(low))
+            )
+
+        if _floor(low) > _ceiling(high):
+            raise ValueError(f"window is empty: min {low} is after max {high}")
+        if not _floor(low) <= _at(ideal, NOON) <= _ceiling(high):
+            raise ValueError(f"ideal {ideal} lies outside min {low}..max {high}")
+        self.min, self.ideal, self.max = low, ideal, high
+        return True
+
+    # ── the curve ────────────────────────────────────────────────────────────
+
+    @property
+    def has_time(self) -> bool:
+        """Whether this window is about moments or about days."""
+        return any(isinstance(v, datetime) for v in (self.min, self.ideal, self.max))
+
+    @property
+    def linear(self) -> bool:
+        """The older shorthand: a flat price per day of deviation, in either direction."""
+        return (
+            self.deviation_cost_per_day is not None
+            or self.earlier_cost_per_day is not None
+            or self.later_cost_per_day is not None
+        )
+
+    def _bounds(self) -> tuple[datetime, datetime, datetime]:
+        """min, ideal, max as moments, in whatever timezone the window speaks."""
+        tz = self.tzinfo
+        return (
+            _at(self.min, time.min, tz),
+            _at(self.ideal, NOON, tz),
+            _at(self.max, time.max, tz),
+        )
+
+    def _span(self, earlier: bool) -> float:
+        """Distance from the ideal to one bound, in the window's own unit."""
+        low, ideal, high = self._bounds()
+        if self.has_time:
+            gap = (ideal - low) if earlier else (high - ideal)
+            return gap.total_seconds() / 3600.0
+        # A window that names no times is about days, and its edges are whole days
+        # away from the ideal — not 11 hours and 59 minutes away.
+        bound = self.min if earlier else self.max
+        return float(abs((_as_date(self.ideal) - _as_date(bound)).days))
+
+    def _tolerance(self, earlier: bool) -> float:
+        """The breadth of the curve, which is the span unless it was stated.
+
+        Distinct from the span on purpose: the bound says what is *possible*, the
+        tolerance says how fast it gets expensive on the way there."""
+        if self.tolerance_hours is not None:
+            return self.tolerance_hours / (1.0 if self.has_time else 24.0)
+        if self.tolerance_days is not None:
+            return self.tolerance_days * (24.0 if self.has_time else 1.0)
+        return self._span(earlier)
+
+    def _deviation(self, when: datetime) -> float:
+        """How far from `ideal`, in the window's own unit.
+
+        A window that names times is measured in hours, because that is the resolution
+        it was written at. One that names only days is measured in whole days: asking
+        it about 05:40 would otherwise invent a preference it never expressed.
+        """
+        _, ideal, _ = self._bounds()
+        if self.has_time:
+            return (when - ideal).total_seconds() / 3600.0
+        return float((when.date() - _as_date(self.ideal)).days)
+
+    @property
+    def tzinfo(self):
+        """The window's own timezone, if it stated one.
+
+        A window written without an offset — "ideal = 2026-10-01T10:00:00" — means
+        local wall-clock time at the airport, which is how every timetable is read.
+        Departure times arrive here timezone-aware, so they are compared on their own
+        wall clock unless the window explicitly says otherwise.
+        """
+        for value in (self.ideal, self.min, self.max):
+            if isinstance(value, datetime) and value.tzinfo is not None:
+                return value.tzinfo
+        return None
+
+    def _align(self, when: datetime) -> datetime:
+        if self.tzinfo is None:
+            return when.replace(tzinfo=None)
+        return when if when.tzinfo else when.replace(tzinfo=self.tzinfo)
+
+    def cost_at(self, when: datetime) -> float | None:
+        """What departing at this moment costs. None means outside the window."""
+        when = self._align(when)
+        low, _, high = self._bounds()
+        if not low <= when <= high:
+            return None
+        delta = self._deviation(when)
+        if self.linear:
+            rate = self.earlier_cost_per_day if delta < 0 else self.later_cost_per_day
+            if rate is None:
+                rate = self.deviation_cost_per_day or 0.0
+            return abs(delta) * (rate / 24.0 if self.has_time else rate)
+        scale = self.cost_at_tolerance
+        if scale is None:
+            scale = DEFAULT_COST_AT_TOLERANCE
+        # In the window's own unit, so the shared curve knows nothing about dates.
+        bounds = curve.Bounds(low=-self._span(earlier=True), ideal=0.0, high=self._span(False))
+        return curve.cost(
+            delta, bounds, scale=scale, tolerance=self._tolerance(earlier=delta < 0)
+        )
+
+    def _best_cost_on(self, day: date) -> float:
+        """The cheapest moment available on this day.
+
+        A timed window cannot be summarized by one number per day without choosing
+        which moment stands for the day — and the only defensible choice is the best
+        one available, since the search is free to pick it. `cost_at` still prices the
+        departure that actually turns up.
+        """
+        low, ideal, high = self._bounds()
+        first = max(low, datetime.combine(day, time.min, tzinfo=self.tzinfo))
+        last = min(high, datetime.combine(day, time.max, tzinfo=self.tzinfo))
+        best = min(max(ideal, first), last)  # the moment nearest `ideal` that day
+        return self.cost_at(best) or 0.0
+
+    # ── reading it back ──────────────────────────────────────────────────────
+
+    @property
+    def dates(self) -> list[date]:
+        return sorted(self.costs)
+
+    def cost_of(self, when: date | datetime) -> float | None:
+        """None means outside the window — not merely expensive.
+
+        A `date` is answered from the compiled map (the best that day); a `datetime`
+        is priced exactly, which is the difference between "Tuesday is fine" and
+        "Tuesday at 05:40 is not what I meant".
+        """
+        if isinstance(when, datetime):
+            return self.cost_at(when) if self._align(when).date() in self.costs else None
+        return self.costs.get(when)
+
+    def with_default_scale(self, scale: float) -> DateWindow:
+        """This window, priced at `scale` if it did not name a scale of its own.
+
+        Intents are loaded before preferences are, so a window that says nothing about
+        what its edges are worth is compiled against a module fallback and then told
+        the owner's own number here. A window that priced itself is returned untouched
+        — the trip-specific statement outranks the standing one.
+        """
+        declared = dict(self._declared)
+        if self.arrive is not None:
+            declared["arrive"] = self.arrive.with_default_scale(scale)
+        if self.cost_at_tolerance is None and not self.linear:
+            declared["cost_at_tolerance"] = scale
+        elif declared.get("arrive") is self.arrive:
+            return self
+        return DateWindow(**declared)
+
+    def priced(self, when: date | datetime) -> DateCost | None:
+        """The cost, carrying whether this window resolves times as well as days."""
+        cost = self.cost_of(when)
+        return None if cost is None else DateCost(cost, self.has_time)
+
+    def describe(self) -> str:
+        """The window in one line, for the assumptions block."""
+        stamp = "%Y-%m-%d %H:%M" if self.has_time else "%Y-%m-%d"
+        span = f"{_floor(self.min):{stamp}}..{_ceiling(self.max):{stamp}}"
+        scale = self.cost_at_tolerance or DEFAULT_COST_AT_TOLERANCE
+        shape = (
+            f"{self.deviation_cost_per_day or self.later_cost_per_day or 0:.0f}/day"
+            if self.linear
+            else f"quadratic, {scale:.0f} at the tolerance"
+        )
+        ideal = f"{_at(self.ideal, NOON):{stamp}}" if self.ideal else str(self.preferred)
+        blocked = f", {len(self.blocked)} blocked" if self.blocked else ""
+        return f"{span}, ideal {ideal} ({shape}{blocked})"
+
+
+class LengthWindow(Strict):
+    """How long a stay should be — the same window, counted in nights (§8.4).
+
+    `min` / `ideal` / `max` and the same quadratic between them, because "five to nine
+    nights, ideally seven" is the same kind of statement as "the 22nd to the 27th,
+    ideally the 24th". Any two of the three are enough; the third is inferred by
+    `cost.curve.resolve`, so "between five and nine" alone means seven is the middle
+    and both ends cost the same.
+
+    The bounds are hard, as everywhere else: `permits` rejects a length outside them
+    rather than pricing it, since a window states what is possible, not what is dear.
+    """
+
+    min_nights: int | None = None
+    ideal_nights: int | None = None
+    max_nights: int | None = None
+    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.
+
+    Negative means you would pay for it; positive means it is a chore. Net because we
+    can guess a hotel rate and cannot guess what the beaches of Punta Cana are worth
+    to a particular person — and only the difference ever enters the ranking (§8.3).
+
+    This is the one place in the model where a cost may go below zero, and the reason
+    it is safe: the square eventually swamps any offset, so a stay worth −800 for a
+    fortnight is worth +∞ for a decade. The curve bounds itself; `max_nights` is then
+    a statement of fact rather than a device to stop the solver running away.
+    """
+
+    def permits(self, nights: int) -> bool:
+        if self.min_nights is not None and nights < self.min_nights:
+            return False
+        return not (self.max_nights is not None and nights > self.max_nights)
+
+    @property
+    def bounds(self) -> curve.Bounds | None:
+        stated = (self.min_nights, self.ideal_nights, self.max_nights)
+        if all(value is None for value in stated):
+            return None
+        # An ideal with no bounds spans one tolerance either side rather than
+        # collapsing to a single night. A lone date means one day and that is right —
+        # you leave on a day — but a stay of "ideally a week" that priced only exactly
+        # seven nights would silently drop its own valuation for every other length.
+        return curve.resolve(*stated, spread=self.tolerance_nights)
+
+    def cost_of(self, nights: int, *, scale: float | None = None) -> float | None:
+        """What a stay of this length costs. None when nothing was stated to price it."""
+        bounds = self.bounds
+        amount = self.cost_at_tolerance if scale is None else (self.cost_at_tolerance or scale)
+        if bounds is None or amount is None:
+            return None
+        return curve.cost(
+            nights,
+            bounds,
+            scale=amount,
+            tolerance=self.tolerance_nights,
+            offset=self.net_at_ideal,
+        )
+
+    def breakeven(self, *, scale: float | None = None) -> tuple[float, float] | None:
+        """The range of lengths over which this stop pays for itself (§8.3)."""
+        bounds = self.bounds
+        amount = self.cost_at_tolerance if scale is None else (self.cost_at_tolerance or scale)
+        if bounds is None or not amount:
+            return None
+        return curve.breakeven(
+            bounds, scale=amount, tolerance=self.tolerance_nights, offset=self.net_at_ideal
+        )
+
+    def describe(self) -> str:
+        bounds = self.bounds
+        if bounds is None:
+            return "any length"
+        worth = f", worth {-self.net_at_ideal:g} at best" if self.net_at_ideal < 0 else ""
+        return f"{bounds.low:g}-{bounds.high:g}n, ideally {bounds.ideal:g}n{worth}"
+
+
+class DurationSpec(LengthWindow):
+    """The trip's own length. `preferred_nights` is the older name for `ideal_nights`."""
+
+    preferred_nights: int | None = None
+
+    @model_validator(mode="after")
+    def _one_ideal(self) -> DurationSpec:
+        if self.preferred_nights is not None and self.ideal_nights is None:
+            self.ideal_nights = self.preferred_nights
+        elif self.ideal_nights is not None and self.preferred_nights is None:
+            self.preferred_nights = self.ideal_nights
+        return self
+
+
+class StopoverSpec(LengthWindow):
+    """A stopover: where, how long, and what a night there is worth.
+
+    Its length is a window like any other — one or three nights in Istanbul are not
+    the same thing, and "ideally two" is exactly the statement the quadratic exists to
+    carry (§8.3, §8.4).
+    """
+
+    where: str | list[str] = "any_enroute_hub"
+    min_nights: int = 1
+    max_nights: int = 3
+
+    @property
+    def places(self) -> list[str] | None:
+        """None means "resolve from the routing" (§8.3 candidates)."""
+        if isinstance(self.where, str):
+            return None if self.where == "any_enroute_hub" else [self.where.upper()]
+        return [p.upper() for p in self.where]
+
+
+class StopSpec(LengthWindow):
+    """A place you are at, and everything you asked for about being there.
+
+    A journey is stops and the legs between them: `n` stops make `n − 1` legs, and
+    every gap between two legs is one of these — a 40-minute transfer, a two-night
+    stopover and the destination stay alike. There is no type distinction, only a
+    valuation, and a place you never mention gets the default, which is a wash (§8.3).
+
+    Each stop carries the same three windows as everything else: when the leg into it
+    should land (`arrive`), how long to stay (the inherited length window), and when
+    the leg out of it should leave (`depart`). Any two fix the third, so stating two is
+    normal. The first stop has no arrival and the last has no departure, because you
+    start at home and end there.
+
+    Addressed by **place**, never by position: the intent is written before any routing
+    exists, and the search compares itineraries with different leg counts, so "the gap
+    after leg 2" means something different in each candidate.
+    """
+
+    place: str = Field(min_length=3, max_length=4)
+    arrive: DateWindow | TimeOfDayWindow | None = None
+    depart: DateWindow | TimeOfDayWindow | None = None
+
+    @model_validator(mode="before")
+    @classmethod
+    def _pick_shapes(cls, data: Any) -> Any:
+        if isinstance(data, dict):
+            for key in ("arrive", "depart"):
+                window = data.get(key)
+                if isinstance(window, dict):
+                    data = {**data, key: _window_from(window)}
+        return data
+
+    @model_validator(mode="after")
+    def _upper(self) -> StopSpec:
+        self.place = self.place.upper()
+        return self
+
+
+def _window_from(raw: dict[str, Any]) -> DateWindow | TimeOfDayWindow:
+    """Clock times mean a window that recurs daily; dates mean an absolute one."""
+    stated = [raw.get(k) for k in ("min", "ideal", "max")]
+    if any(isinstance(v, time) and not isinstance(v, datetime) for v in stated):
+        return TimeOfDayWindow.model_validate(raw)
+    return DateWindow.model_validate(raw)
+
+
+class StopoverPolicy(Strict):
+    allow: bool = True
+    specs: list[StopoverSpec] = Field(default_factory=list)
+
+
+class ConstraintSpec(Strict):
+    """The TOML form of a hard requirement (§8.1)."""
+
+    kind: ConstraintKind
+    when: datetime
+    place: str | None = None
+    buffer_hours: float = 12.0
+    criticality: Criticality = Criticality.SERIOUS
+    violation_cost: float | None = None
+    label: str = ""
+
+    def to_constraint(self) -> HardConstraint:
+        return HardConstraint(
+            kind=self.kind,
+            when=self.when,
+            place=self.place.upper() if self.place else None,
+            buffer_hours=self.buffer_hours,
+            criticality=self.criticality,
+            violation_cost=self.violation_cost,
+            label=self.label,
+        )
+
+
+class LegSpec(Strict):
+    """Per-leg valuation overrides — a few numbers, not a trip type (§8.1)."""
+
+    preferences: dict[str, Any] = Field(default_factory=dict)
+    note: str = ""
+
+
+class BudgetSpec(Strict):
+    max_queries_total: int = 120
+    max_queries_per_oracle: int | None = None
+    max_wallclock_minutes: float = 25.0
+
+
+class TravelIntent(Strict):
+    origins: list[PlaceSpec] = Field(min_length=1)
+    destinations: list[PlaceSpec] = Field(min_length=1)
+    trip_shape: TripShape = TripShape.RETURN
+    outbound: DateWindow | None = None
+    """When the first leg leaves. Optional when the journey says it itself."""
+    inbound: DateWindow | None = None
+    duration: DurationSpec = Field(default_factory=DurationSpec)
+    stops: list[StopSpec] = Field(default_factory=list)
+    """Named stops with their own length windows — the destination included (§8.3)."""
+    stopovers: StopoverPolicy = Field(default_factory=StopoverPolicy)
+    constraints: list[ConstraintSpec] = Field(default_factory=list)
+    party: list[str] = Field(default_factory=lambda: ["owner"])
+    cabin: Cabin = Cabin.ECONOMY
+    baggage_profile: BaggageProfile = BaggageProfile.CABIN_BAG
+    preferences: dict[str, Any] = Field(default_factory=dict)
+    """Per-trip overrides of the valuation profile."""
+    legs: dict[int, LegSpec] = Field(default_factory=dict)
+    pos_probing: str = "shortlist_only"
+    budget: BudgetSpec = Field(default_factory=BudgetSpec)
+    normalize_currency: str = "EUR"
+    notes: str = ""
+
+    @model_validator(mode="after")
+    def _check_shape(self) -> TravelIntent:
+        if (
+            self.trip_shape is TripShape.RETURN
+            and self.inbound is None
+            and self.duration.min_nights is None
+        ):
+            raise ValueError(
+                "a return trip needs either an `inbound` window or a `duration` "
+                "(otherwise there is nothing to search over)"
+            )
+        if self.trip_shape is TripShape.ONE_WAY and self.inbound is not None:
+            raise ValueError("a one-way trip cannot have an inbound window")
+        return self
+
+    @property
+    def hard_constraints(self) -> list[HardConstraint]:
+        return [c.to_constraint() for c in self.constraints]
+
+    @model_validator(mode="after")
+    def _windows_from_the_journey(self) -> TravelIntent:
+        """A journey written out in full already states its own departure windows.
+
+        Rather than have two sources of truth, the directional names are *derived* from
+        the journey when it supplies them: `outbound` is the leg out of home, `inbound`
+        the leg out of the last stop before home. Everything downstream — the oracles,
+        the date-pair projection, the report — keeps speaking the language sites speak.
+        """
+        written_out = self.stops and self.stops[0].place == self.origins[0].code
+        if written_out:
+            if self.outbound is None:
+                self.outbound = self.stops[0].depart
+            if self.inbound is None and len(self.stops) > 2:
+                self.inbound = self.stops[-2].depart
+        if self.outbound is None:
+            raise ValueError(
+                "a journey needs somewhere to start: give [date_windows.outbound], "
+                "or a first stop with a `depart` window"
+            )
+        return self
+
+    @property
+    def journey(self) -> list[StopSpec]:
+        """The trip as places in order, whichever way it was written (§8.3).
+
+        There is no outbound and no inbound. A return trip is three stops — home, the
+        destination, home — and an open jaw or a four-city trip is the same list with
+        different entries. `origins`/`destinations`/`date_windows`/`duration` remain a
+        perfectly good way to say the common case, and compile to exactly this:
+
+            [BUD  depart=outbound]
+            [LIS  arrive=outbound.arrive, length=duration, depart=inbound]
+            [BUD  arrive=inbound.arrive]
+
+        Stated stops slot into the middle, so `[[stops]]` alone gives a multi-city
+        journey without repeating the endpoints.
+        """
+        home = self.origins[0].code
+        middle = list(self.stops)
+        if not middle:
+            middle = [
+                StopSpec(
+                    place=self.destinations[0].code,
+                    min_nights=self.duration.min_nights,
+                    ideal_nights=self.duration.ideal_nights,
+                    max_nights=self.duration.max_nights,
+                    cost_at_tolerance=self.duration.cost_at_tolerance,
+                    tolerance_nights=self.duration.tolerance_nights,
+                )
+            ]
+        if middle[0].place == home:  # the journey was written out in full
+            stops = middle
+        else:
+            stops = [StopSpec(place=home), *middle]
+            if self.trip_shape is not TripShape.ONE_WAY:
+                stops.append(StopSpec(place=home))
+
+        # `[duration]` is a length window for the destination stay, so a stop that
+        # named itself but not its length still inherits the bounds — otherwise
+        # writing `[[stops]]` would silently drop "five to nine nights".
+        destinations = {place.code for place in self.destinations}
+        for stop in stops[1:-1] if len(stops) > 2 else stops[1:]:
+            if stop.place not in destinations:
+                continue
+            for field_name in ("min_nights", "ideal_nights", "max_nights"):
+                if getattr(stop, field_name) is None:
+                    setattr(stop, field_name, getattr(self.duration, field_name))
+
+        # The older surface names the same windows; it just names them by direction.
+        if stops[0].depart is None:
+            stops[0].depart = self.outbound
+        if len(stops) > 1 and stops[1].arrive is None:
+            stops[1].arrive = self.outbound.arrive
+        if self.inbound is not None and len(stops) > 2:
+            if stops[-2].depart is None:
+                stops[-2].depart = self.inbound
+            if stops[-1].arrive is None:
+                stops[-1].arrive = self.inbound.arrive
+        return stops
+
+    @property
+    def stopover_requests(self) -> dict[str, StopoverSpec | StopSpec]:
+        """Named places the intent asked for, by airport code.
+
+        `any_enroute_hub` specs are not here: they are resolved against the routing
+        during the search, which is where discovered stops come from (§8.3). A
+        `[[stops]]` entry wins over a `[stopovers]` spec for the same place, being the
+        more specific way of saying it.
+        """
+        out: dict[str, StopoverSpec | StopSpec] = {}
+        if self.stopovers.allow:
+            for spec in self.stopovers.specs:
+                for place in spec.places or ():
+                    out[place] = spec
+        for stop in self.stops:
+            out[stop.place] = stop
+        return out
+
+    def departure_sets(self, *, limit: int = MAX_DATE_COMBINATIONS) -> list[tuple[date, ...]]:
+        """Every combination of leg departure dates the journey allows.
+
+        One entry per leg, in order, so a three-stop trip yields pairs and a four-stop
+        one yields triples. Each stop's length window filters the combinations as they
+        are built rather than after: with `k` legs the product is exponential, and
+        generating it in full before filtering is how an intent with wide windows turns
+        into an out-of-memory error instead of a budget warning.
+
+        This is the search space the solver spends its budget over, so it is also the
+        first place a badly-specified intent shows up — `limit` truncates rather than
+        letting a five-city trip with three-week windows enumerate for an hour.
+        """
+        stops = self.journey
+        legs = [stop.depart for stop in stops[:-1]]
+        if any(window is None for window in legs):
+            return []
+
+        combinations: list[tuple[date, ...]] = [()]
+        for index, window in enumerate(legs):
+            grown: list[tuple[date, ...]] = []
+            for prefix in combinations:
+                for day in window.dates:  # type: ignore[union-attr]
+                    if prefix:
+                        nights = (day - prefix[-1]).days
+                        # The stop between these two legs has to be a real stay of an
+                        # allowed length; anything else is a different trip.
+                        if nights <= 0 or not stops[index].permits(nights):
+                            continue
+                    grown.append((*prefix, day))
+                    if len(grown) >= limit:
+                        break
+                if len(grown) >= limit:
+                    break
+            combinations = grown
+        return combinations
+
+    def date_pairs(self) -> list[tuple[date, date | None]]:
+        """The two-leg view of `departure_sets`, which is what the oracles can ask.
+
+        Sites sell one-ways and round trips; a four-city journey is not a query anyone
+        can send. So the journey is the model and this is the projection of it that the
+        adapters speak (DESIGN §8.3).
+        """
+        sets = self.departure_sets()
+        if len(self.journey) < 3:
+            return [(days[0], None) for days in sets]
+        return [(days[0], days[-1]) for days in sets]
+
+    def stop_windows(self):
+        """The journey in the shape the cost model wants: place plus two callables."""
+        from layover.cost.generalized import StopWindows
+
+        return [
+            StopWindows(
+                place=stop.place,
+                arrive=stop.arrive.priced if stop.arrive else None,
+                depart=stop.depart.priced if stop.depart else None,
+            )
+            for stop in self.journey
+        ]
+
+    def with_flexibility_default(
+        self, scale: float, length_scale: float | None = None
+    ) -> TravelIntent:
+        """The intent with any unpriced window resolved against preferences.
+
+        Moments and lengths take different scales, since "a day later than I wanted to
+        leave" and "a night longer than I wanted to stay" are not the same regret.
+        """
+        update = {
+            "outbound": self.outbound.with_default_scale(scale),
+            "inbound": self.inbound.with_default_scale(scale) if self.inbound else None,
+        }
+        if length_scale is not None and self.duration.cost_at_tolerance is None:
+            update["duration"] = self.duration.model_copy(
+                update={"cost_at_tolerance": length_scale}
+            )
+        return self.model_copy(update=update)
+
+    def date_costs(self) -> dict[date, float]:
+        """Both windows merged into one map, as the cost model expects (§8.4).
+
+        Day granularity: each date is worth what its best departure moment is worth.
+        `departure_cost` is the sharper instrument when the actual time is known.
+        """
+        costs = dict(self.outbound.costs)
+        if self.inbound is not None:
+            costs.update(self.inbound.costs)
+        return costs
+
+    def arrival_cost(self, when: datetime) -> DateCost | None:
+        """When the outbound should land, if the intent said."""
+        window = self.outbound.arrive
+        return window.priced(when) if window else None
+
+    def return_departure_cost(self, when: datetime) -> DateCost | None:
+        return self.inbound.priced(when) if self.inbound else None
+
+    def return_arrival_cost(self, when: datetime) -> DateCost | None:
+        """When to be home again — usually the one that is actually promised."""
+        window = self.inbound.arrive if self.inbound else None
+        return window.priced(when) if window else None
+
+    def duration_cost(self, nights: int) -> float | None:
+        return self.duration.cost_of(nights)
+
+    def departure_cost(self, when: datetime) -> DateCost | None:
+        """What leaving at this exact moment costs, under whichever window covers it.
+
+        The inbound window wins where the two overlap, matching `date_costs`. A moment
+        neither window covers returns None, which the cost model reads as "this window
+        has nothing to say" rather than as free.
+        """
+        return self.outbound.priced(when)
+
+
+def load_intent(path: Path) -> TravelIntent:
+    """Read an intent file. Unknown keys are errors, not silently ignored."""
+    raw = tomllib.loads(Path(path).read_text())
+    raw["origins"] = [PlaceSpec.parse(v) for v in _as_list(raw.get("origins", []))]
+    raw["destinations"] = [PlaceSpec.parse(v) for v in _as_list(raw.get("destinations", []))]
+
+    windows = raw.pop("date_windows", None)
+    if windows:
+        raw.setdefault("outbound", windows.get("outbound"))
+        if windows.get("inbound") is not None:
+            raw.setdefault("inbound", windows["inbound"])
+
+    legs = raw.get("legs")
+    if isinstance(legs, dict):
+        raw["legs"] = {int(k): v for k, v in legs.items()}
+    return TravelIntent.model_validate(raw)
+
+
+def _as_list(value: Any) -> list[Any]:
+    if isinstance(value, list):
+        return value
+    return [value]