layover 0.1.0.dev0__py3-none-any.whl

layover/cli.py

@@ -0,0 +1,1137 @@
+"""The command line (DESIGN §11).
+
+M0's slice: read an intent, ask one oracle, normalize, price every result under the
+owner's own valuations, and print the ranking with the reason attached. No solver yet
+— no split probes, no date sweep, no budget allocation — so this asks exactly one
+question per run and says so.
+
+What it will not do: print a number it cannot defend. Every row shows the money that
+leaves the account beside the generalized cost that ordered it, plus what had to be
+assumed to get there.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from datetime import datetime
+from functools import partial
+from pathlib import Path
+
+from layover.cost.delay import DelayTable
+from layover.cost.generalized import (
+    CostKind,
+    PricingContext,
+    StopoverRequest,
+    align,
+)
+from layover.currency import RateCache, default_cache_path
+from layover.intent import TravelIntent, load_intent
+from layover.models import POSContext, TripPlan, TripShape
+from layover.oracles.api.azair import AzairOracle, parse_combinations
+from layover.oracles.api.google_flights import GoogleFlightsOracle
+from layover.oracles.api.serpapi_flights import (
+    PriceInsight,
+    SerpApiGoogleFlights,
+    airport_countries,
+)
+from layover.oracles.base import OracleQuery
+from layover.oracles.consent import CookieJar, NotAConsentCookie, parse_cookie
+from layover.oracles.knowledge import OracleKnowledge
+from layover.oracles.transport import HttpTransport, check_egress, is_eu_egress
+from layover.prefs.profile import PreferenceProfile, load_preferences
+from layover.prefs.travelers import Party, Traveler, load_travelers
+from layover.session import default_session_root, gc, open_session
+from layover.solver import search
+from layover.solver.budget import QueryBudget, Question, Quote, route
+
+REPO_CONFIG = Path(__file__).resolve().parents[2] / "config"
+
+
+def _config_paths() -> list[Path]:
+    return [
+        REPO_CONFIG / "preferences.toml",
+        Path.home() / ".config" / "layover" / "preferences.toml",
+    ]
+
+
+def _party_for(intent: TravelIntent) -> Party:
+    """Load the travellers named by the intent; fall back to a nameless adult.
+
+    A missing `travelers.toml` is normal on a first run — it means no passports and
+    no lounge quota are known, and the report will say so rather than inventing them.
+    """
+    known = load_travelers(Path.home() / ".config" / "layover" / "travelers.toml")
+    travelers = [known.get(name, Traveler(id=name)) for name in intent.party]
+    return Party(travelers=travelers or [Traveler(id="owner")])
+
+
+def _pricing_context(
+    intent: TravelIntent, prefs: PreferenceProfile, party: Party
+) -> PricingContext:
+    stopovers = {
+        place: StopoverRequest(
+            place=place,
+            min_nights=spec.min_nights,
+            max_nights=spec.max_nights,
+            ideal_nights=spec.ideal_nights,
+            cost_at_tolerance=spec.cost_at_tolerance,
+            tolerance_nights=spec.tolerance_nights,
+            net_at_ideal=spec.net_at_ideal,
+        )
+        for place, spec in intent.stopover_requests.items()
+    }
+    return PricingContext(
+        prefs=prefs,
+        party=party,
+        destinations=frozenset(place.code for place in intent.destinations),
+        constraints=intent.hard_constraints,
+        prefs_by_leg={
+            index: prefs.with_overrides(leg.preferences)
+            for index, leg in intent.legs.items()
+            if leg.preferences
+        },
+        baggage_profile=intent.baggage_profile,
+        stopovers=stopovers,
+        date_costs=intent.date_costs(),
+        journey=intent.stop_windows(),
+        duration_cost=intent.duration_cost,
+        stopover_length_scale=prefs.flexibility.length_cost_at_tolerance,
+        preferred_nights=intent.duration.preferred_nights,
+        delay_table=_delay_table(),
+        regimes=_regimes(),
+    )
+
+
+def _regimes():
+    """Transit regimes, when the reference data is present (§8.6)."""
+    from layover.cost.borders import RegimeTable
+
+    root = REPO_CONFIG.parent / "reference"
+    regimes = root / "transit_regimes.toml"
+    authorizations = root / "authorizations.toml"
+    if regimes.is_file() and authorizations.is_file():
+        return RegimeTable.from_toml(regimes, authorizations)
+    return None
+
+
+def _delay_table() -> DelayTable:
+    path = REPO_CONFIG.parent / "reference" / "delay_profiles.toml"
+    return DelayTable.from_toml(path) if path.is_file() else DelayTable.fallback()
+
+
+def _search(args: argparse.Namespace) -> int:
+    intent = load_intent(Path(args.intent))
+    prefs = load_preferences(_config_paths(), overrides=intent.preferences)
+    # Intents load before preferences do, so a window that did not price its own edges
+    # is told the owner's standing number now (§8.4).
+    intent = intent.with_flexibility_default(
+        prefs.flexibility.date_cost_at_tolerance,
+        prefs.flexibility.length_cost_at_tolerance,
+    )
+    party = _party_for(intent)
+    context = _pricing_context(intent, prefs, party)
+    rates = RateCache(default_cache_path()).get()
+    target = intent.normalize_currency
+    depart, back = intent.date_pairs()[0]
+
+    pos = POSContext(
+        currency=args.currency or target, locale=args.locale, site_market=args.market
+    )
+    probe = HttpTransport(pos=pos)
+    egress = probe.detect_egress_country()
+    if egress is None:
+        egress = probe.detect_egress_country()  # one retry: these lookups are flaky
+    # serpapi fetches on our behalf, so our own exit does not label its prices.
+    refusal = check_egress(egress, override=args.allow_unknown_exit or args.oracle == "serpapi")
+    if refusal:
+        print(f"refusing: {refusal}")
+        return 3
+    if egress is None:
+        print("exit: unknown — recording anyway (--allow-unknown-exit)")
+    print(f"exit: {egress or 'unknown'}", end="")
+    print(f"   oracle: {args.oracle}   party: {len(party.travelers)}")
+
+    knowledge = OracleKnowledge()
+    if args.recheck_coverage:
+        knowledge.ttl_days = 0  # ask again about everything, however recently learned
+
+    with open_session(
+        Path(args.sessions or default_session_root()),
+        args.session or datetime.now().strftime("%Y%m%d-%H%M%S"),
+        intent={"file": str(args.intent)},
+        normalize_currency=target,
+    ) as store:
+        budget = QueryBudget(
+            max_queries=intent.budget.max_queries_total,
+            max_money=args.max_money,
+            currency=target,
+        )
+        attempts, quotes = (
+            _choose_oracles(intent, pos, args, store, knowledge, budget)
+            if args.oracle == "auto"
+            else ([args.oracle], {})
+        )
+        # The oracles answer a wider question than the intent asked: AZair's flexi
+        # search has no "earliest return" parameter at all, and nothing lets us say
+        # "land before midnight". So the windows' hard edges are enforced here (§8.4).
+        keep = partial(within_windows, intent)
+
+        result = None
+        for index, name in enumerate(attempts):
+            if index:
+                print(f"  falling back to {name}")
+            ask = _asker(
+                name, intent, pos, egress, store, rates, target, args, context, knowledge
+            )
+            result = search.run(
+                _baseline_query(intent, pos, args, depart, back),
+                ask,
+                context,
+                budget,
+                quotes.get(name) or _quote_for(name),
+                admissible=keep,
+                permits=_stay_permits(intent),
+                probe=args.probe and _probe_would_learn(name),
+            )
+            if result.ranked:
+                break
+
+        if result is None or not result.ranked:
+            print("  no oracle could answer — see the notes above")
+            return 2
+
+        for finding in result.findings:
+            spent = f"{finding.queries} quer{'y' if finding.queries == 1 else 'ies'}"
+            print(f"  {finding.phase}: {spent} — {finding.note}")
+        for note in budget.notes:
+            print(f"     note: {note}")
+        print(f"  {result.improvement()}   ({budget.describe()})")
+
+        _print_table(
+            result.ranked,
+            target=target,
+            rates_as_of=rates.as_of if rates else None,
+            rows=args.rows,
+            explain=args.explain,
+        )
+    return 0
+
+
+ORACLES = {
+    "azair": AzairOracle,
+    "google": GoogleFlightsOracle,
+    "serpapi": SerpApiGoogleFlights,
+}
+
+
+def _quote_for(name: str) -> Quote:
+    """What one query to a named oracle costs when the router was not consulted.
+
+    `--oracle serpapi` skips routing, and treating a credit as free there would let a
+    probe spend money the budget was told not to spend."""
+    oracle = ORACLES.get(name)
+    money = oracle.capabilities.money_cost_per_query if oracle else 0.0
+    return Quote(name, 1, money, True, "single query")
+
+
+def _probe_would_learn(name: str) -> bool:
+    """Whether return-vs-one-ways can tell this oracle anything it did not say.
+
+    AZair's baseline answer is *already* composed one-ways, so the probe would spend
+    two queries rediscovering the plans it just returned. A probe that cannot learn
+    anything is not cheap, it is wasted (DESIGN §6).
+    """
+    oracle = ORACLES.get(name)
+    return not (oracle and oracle.capabilities.composes_one_ways)
+
+
+def _stay_permits(intent: TravelIntent):
+    """The destination stop's length bounds, so a probe cannot invent a longer trip."""
+    stops = intent.journey
+    destination = stops[1] if len(stops) > 2 else None
+    return destination.permits if destination is not None else None
+
+
+def _baseline_query(intent, pos, args, depart, back) -> OracleQuery:
+    """One query describing the whole question, windows included where they help."""
+    dates = intent.outbound.dates
+    inbound_dates = intent.inbound.dates if intent.inbound else None
+    return OracleQuery(
+        origin=intent.origins[0].code,
+        destination=intent.destinations[0].code,
+        depart=dates[0],
+        trip_shape=intent.trip_shape,
+        return_on=inbound_dates[0] if inbound_dates else None,
+        depart_until=dates[-1],
+        return_until=inbound_dates[-1] if inbound_dates else None,
+        min_nights=intent.duration.min_nights,
+        max_nights=intent.duration.max_nights,
+        adults=len(intent.party),
+        cabin=intent.cabin,
+        max_stops=args.max_stops,
+        pos=pos,
+    )
+
+
+def _asker(name, intent, pos, egress, store, rates, target, args, context, knowledge):
+    """One callable per oracle: send this query, return what it offered.
+
+    The solver deals in questions, not in adapters — so the difference between a
+    windowed AZair request and a per-date SerpAPI one lives here and nowhere else.
+    """
+    if name == "azair":
+        return partial(
+            _search_azair, intent, pos, egress, store, rates, target, args, knowledge
+        )
+    if name == "serpapi":
+        return partial(
+            _search_serpapi, intent, pos, store, rates, target, args, context, knowledge
+        )
+    return partial(_search_google, intent, pos, egress, store, rates, target, knowledge)
+
+
+COOLDOWN_MINUTES = {"blocked": 120.0, "captcha": 120.0, "rate_limited": 30.0}
+COVERAGE_EVIDENCE_DAYS = 3
+"""How wide a query must be before an empty answer says anything about coverage."""
+
+
+def _asks_about_a_window(query) -> bool:
+    span = (query.depart_until or query.depart) - query.depart
+    return span.days + 1 >= COVERAGE_EVIDENCE_DAYS
+
+
+def _remember(knowledge: OracleKnowledge, result, route_name: str, query=None) -> None:
+    """Write the durable consequences of one query to the notebook (DESIGN §5).
+
+    Three kinds of fact, and only three: this source cannot answer about this route,
+    this source is unhappy with us right now, this source is fine. None of them is a
+    price, so none of them is hoarding.
+    """
+    kind = str(result.failure).split(".")[-1].lower() if result.failure else ""
+    if result.ok:
+        knowledge.record_coverage(result.oracle_id, route_name, covered=True)
+        knowledge.record_success(result.oracle_id)
+    elif kind == "empty_market":
+        # An answer, not a failure: the site looked and there is nothing it sells.
+        # But only a *wide* question is evidence about coverage. A single date with
+        # nothing on it means "not that Tuesday", and writing that down as "does not
+        # fly there" would poison every later session for a route the site serves —
+        # the exact failure the store is supposed to prevent, inverted.
+        if query is None or _asks_about_a_window(query):
+            knowledge.record_coverage(
+                result.oracle_id, route_name, covered=False, detail=result.detail[:200]
+            )
+    elif kind in COOLDOWN_MINUTES:
+        knowledge.record_failure(
+            result.oracle_id, kind, cooldown_minutes=COOLDOWN_MINUTES[kind]
+        )
+    elif kind:
+        knowledge.record_failure(result.oracle_id, kind)
+
+
+def _choose_oracles(intent, pos, args, store, knowledge: OracleKnowledge, budget):
+    """Ask the cheapest oracle that can answer, and show the reckoning.
+
+    The comparison that matters is the cost of answering the *question*, not of one
+    query: AZair prices a whole window in one request, while the per-date oracles pay
+    for every date pair — which for a 5×5 window is the difference between one query
+    and twenty-five (DESIGN §6).
+    """
+    depart, back = intent.date_pairs()[0]
+    question = Question(
+        query=OracleQuery(
+            origin=intent.origins[0].code,
+            destination=intent.destinations[0].code,
+            depart=depart,
+            trip_shape=intent.trip_shape,
+            return_on=back if intent.trip_shape is TripShape.RETURN else None,
+            adults=len(intent.party),
+            cabin=intent.cabin,
+            pos=pos,
+        ),
+        date_pairs=len(intent.date_pairs()),
+    )
+    available = [AzairOracle(), GoogleFlightsOracle(), SerpApiGoogleFlights()]
+    # What this session already learned: an oracle that said "not covered" for this
+    # route has answered, and asking again would spend the budget on a known answer.
+    excluded = {
+        event["oracle_id"]: "answered 'not covered' earlier this session"
+        for event in store.health_events()
+        if event["kind"] == "empty_market" and question.route in (event["detail"] or "")
+    }
+    # ...and what *earlier* sessions learned. AZair told us it does not fly to Bangkok
+    # in August; a fresh session in September should not have to spend a query
+    # rediscovering that, and a source cooling off from a block is still cooling.
+    for oracle_id in knowledge.excluded_for(question.route):
+        fact = knowledge.coverage(oracle_id, question.route)
+        age = f", learned {fact.age_days()}d ago" if fact else ""
+        excluded[oracle_id] = f"does not cover {question.route}{age}"
+    for oracle in available:
+        until = knowledge.cooling(oracle.id)
+        if until and oracle.id not in excluded:
+            failure = knowledge.health(oracle.id).get("last_failure", "a failure")
+            excluded[oracle.id] = f"cooling until {until:%H:%M} after {failure}"
+    routing = route(available, question, budget, excluded=excluded)
+
+    print(
+        f"routing {question.route}, {question.date_pairs} date pair(s), "
+        f"budget {budget.max_queries} queries / {budget.max_money:,.2f} "
+        f"{budget.currency}:"
+    )
+    print(routing.explain(budget.currency))
+    for note in budget.notes:
+        print(f"     note: {note}")
+    if routing.chosen is None:
+        print("  nothing affordable can answer this — raise --max-money or the budget")
+        return [], {}
+    names = {
+        "azair": "azair",
+        "google_flights": "google",
+        "serpapi_google_flights": "serpapi",
+    }
+    # The whole preference order, not just the winner: an oracle that comes back
+    # blocked has not answered the question, and the budget was drawn up for the
+    # question rather than for one attempt at it. The quotes travel with it, so a
+    # probe can be declined up front instead of abandoned halfway through.
+    order = [names[option.oracle_id] for option in routing.fallbacks]
+    quotes = {names[option.oracle_id]: option for option in routing.fallbacks}
+    return order, quotes
+
+
+def within_windows(intent: TravelIntent, plan: TripPlan) -> bool:
+    """Does every moment the intent has a window for fall inside it?
+
+    Window bounds are hard by construction (§8.4): outside them the trip does not
+    exist. Dropping such a plan is not fussiness — pricing it would rank a date the
+    owner ruled out *above* the ones they asked for, since a moment outside a window
+    has no flexibility cost to pay and therefore looks free.
+
+    Checked at the planned stops (`align`), so a connection is never mistaken for a
+    departure the owner chose.
+    """
+    journey = intent.journey
+    moments = align(plan, [stop.place for stop in journey])
+    for stop, actual in zip(journey, moments, strict=False):
+        for when, window in ((actual.arrive, stop.arrive), (actual.depart, stop.depart)):
+            if when is not None and window is not None and window.cost_of(when) is None:
+                return False
+    return True
+
+
+def _search_azair(intent, pos, egress, store, rates, target, args, knowledge, query):
+    """One windowed query; AZair prices the whole date range at once.
+
+    Each direction is asked about its *own* window. Collapsing both into one span —
+    earliest outbound to latest return — is a wider question than the intent asked,
+    and the extra answers are not free: a return outside the inbound window is
+    infeasible, but it arrives priced like any other and outranks the real ones,
+    because a date the window never covered has no flexibility cost to pay (§8.4).
+    """
+    transport = HttpTransport(pos=pos, egress_country=egress)
+    print(f"searching {query.describe()}")
+    result = AzairOracle(transport=transport).search(query)
+    record = store.record_query(
+        oracle_id=result.oracle_id,
+        dedup_key=query.dedup_key,
+        request={"query": query.describe()},
+        status=result.status,
+        failure_kind=str(result.failure) if result.failure else None,
+        latency_ms=result.latency_ms,
+    )
+    _remember(knowledge, result, f"{query.origin}-{query.destination}", query)
+    if not result.ok:
+        store.record_health(result.oracle_id, result.status, result.detail[:200])
+        print(f"  {result.status}: {result.detail}")
+        return []
+
+    combinations = parse_combinations(result.raw, query, pos=transport.pos_with_egress())
+    plans: list[TripPlan] = []
+    for combination, offers in combinations:
+        for offer in offers:
+            offer.price_normalized = (
+                rates.try_convert(offer.price.amount, offer.price.currency, target)
+                if rates
+                else offer.price.amount
+            )
+        store.record_offers(record.id, offers)
+        plans.append(TripPlan(offers=offers, plan_id=combination.result_id))
+    print(
+        f"  {len(combinations)} combinations, {sum(len(o) for _c, o in combinations)} "
+        f"tickets in {result.latency_ms:.0f}ms — one query covered the whole window"
+    )
+    return plans
+
+
+def _search_serpapi(intent, pos, store, rates, target, args, context, knowledge, query):
+    """Google's data, fetched by someone with a contract to do it.
+
+    No exit to worry about — they fetch, so the consent wall never appears — but every
+    query is a credit, which is why the cap is checked before the request and the
+    remaining allowance is printed after it.
+    """
+    oracle = SerpApiGoogleFlights(monthly_cap=args.serpapi_cap)
+    print(
+        f"searching {query.describe()}  ({oracle.remaining} of "
+        f"{args.serpapi_cap} credits left this month)"
+    )
+    result = oracle.search(query)
+    record = store.record_query(
+        oracle_id=result.oracle_id,
+        dedup_key=query.dedup_key,
+        request={"query": query.describe()},
+        status=result.status,
+        failure_kind=str(result.failure) if result.failure else None,
+        latency_ms=result.latency_ms,
+    )
+    _remember(knowledge, result, f"{query.origin}-{query.destination}", query)
+    if not result.ok:
+        store.record_health(result.oracle_id, result.status, result.detail[:200])
+        print(f"  {result.status}: {result.detail}")
+        return []
+    for offer in result.offers:
+        offer.price_normalized = (
+            rates.try_convert(offer.price.amount, offer.price.currency, target)
+            if rates
+            else offer.price.amount
+        )
+    store.record_offers(record.id, result.offers)
+    print(
+        f"  {len(result.offers)} offers in {result.latency_ms:.0f}ms, "
+        f"{oracle.remaining} credits left"
+    )
+    # The response names each airport's country, so border costs stop needing a
+    # hand-written mapping for the airports a search actually touches (§8.6).
+    countries = airport_countries(result.raw or {})
+    if countries:
+        context.transit_countries = {**countries, **context.transit_countries}
+    insight = PriceInsight.from_payload(result.raw or {})
+    if insight:
+        print(f"  source price context: {insight.describe(target)}")
+    return [
+        TripPlan(offers=[offer], plan_id=f"s{index}")
+        for index, offer in enumerate(result.offers)
+    ]
+
+
+def _search_google(intent, pos, egress, store, rates, target, knowledge, query):
+    """One date pair per query; Google is asked about a single itinerary shape."""
+    cookies, problems = CookieJar.load().usable_for("google.com", egress=egress)
+    for problem in problems:
+        print(f"  consent cookie: {problem}")
+    transport = HttpTransport(pos=pos, cookies=cookies, egress_country=egress)
+    print(f"searching {query.describe()}")
+    result = GoogleFlightsOracle(transport=transport).search(query)
+    record = store.record_query(
+        oracle_id=result.oracle_id,
+        dedup_key=query.dedup_key,
+        request={"query": query.describe()},
+        status=result.status,
+        failure_kind=str(result.failure) if result.failure else None,
+        latency_ms=result.latency_ms,
+    )
+    _remember(knowledge, result, f"{query.origin}-{query.destination}", query)
+    if not result.ok:
+        store.record_health(result.oracle_id, result.status, result.detail[:200])
+        print(f"  {result.status}: {result.detail}")
+        return []
+    for offer in result.offers:
+        offer.price_normalized = (
+            rates.try_convert(offer.price.amount, offer.price.currency, target)
+            if rates
+            else offer.price.amount
+        )
+    store.record_offers(record.id, result.offers)
+    print(f"  {len(result.offers)} offers in {result.latency_ms:.0f}ms")
+    return [
+        TripPlan(offers=[offer], plan_id=f"g{index}")
+        for index, offer in enumerate(result.offers)
+    ]
+
+
+def _print_table(ranked, *, target: str, rates_as_of, rows: int, explain: int) -> None:
+    """The ranking, with the arithmetic visible rather than trailing one row.
+
+    Each row shows what its generalized cost is made of, because a number you cannot
+    take apart is a number you have to trust — and the point of this project is not
+    having to.
+    """
+    kinds = [
+        ("fare", (CostKind.FARE, CostKind.ANCILLARY)),
+        ("time", (CostKind.TRAVEL_TIME, CostKind.EXPECTED_DELAY)),
+        ("wait", (CostKind.INVOLUNTARY_WAIT, CostKind.LOUNGE)),
+        ("stop", (CostKind.STOPOVER,)),
+        ("flex", (CostKind.DATE_FLEXIBILITY, CostKind.DURATION_DEVIATION)),
+        ("brdr", (CostKind.BORDER, CostKind.GROUND_TRANSFER)),
+        ("disc", (CostKind.DISCOMFORT,)),
+        ("risk", (CostKind.RISK_PREMIUM,)),
+    ]
+    header = f"  {'#':>3} {'total':>7} {'money':>6}"
+    header += "".join(f"{name:>6}" for name, _ in kinds)
+    header += "  tk  route"
+    print("\n" + header)
+    print("  " + "─" * (len(header) + 12))
+
+    for index, (cost, plan) in enumerate(ranked[:rows], start=1):
+        segments = plan.segments
+        route = "-".join([segments[0].origin] + [s.destination for s in segments])
+        parts = "".join(
+            f"{sum(cost.by_kind(k).mid for k in group):>6.0f}" for _name, group in kinds
+        )
+        money = plan.money_out_of_pocket
+        flag = " " if cost.feasible else "!"
+        # How a plan was arrived at belongs on its row: two itineraries with the same
+        # fare are not the same offer when one of them is two separate bookings.
+        shape = f"  [{plan.label}]" if plan.label else ""
+        print(
+            f"  {index:>2}{flag} {cost.generalized_cost.mid:>7,.0f} "
+            f"{(money or 0):>6.0f}{parts}  {len(plan.offers):>2}  {route}{shape}"
+        )
+
+    print(
+        f"\n  columns are the generalized cost broken into its parts, all in {target}", end=""
+    )
+    if rates_as_of:
+        print(f" (ECB {rates_as_of})", end="")
+    print(".")
+    print("  fare+time+wait+stop+flex+brdr+disc+risk = total.  tk = tickets to buy.")
+    print("  '!' = a hard constraint or a connection rule was broken.")
+
+    for index, (cost, plan) in enumerate(ranked[:explain], start=1):
+        segments = plan.segments
+        route = "-".join([segments[0].origin] + [s.destination for s in segments])
+        print(f"\n  #{index}  {route}  —  {cost.generalized_cost.mid:,.0f} {target}")
+        for line in cost.lines:
+            print(f"    {line}")
+        if cost.risks:
+            for risk in cost.risks:
+                print(f"    risk: {risk.kind} — {risk.detail}")
+        for reason in cost.infeasible_reasons:
+            print(f"    INFEASIBLE: {reason}")
+        for opportunity in cost.opportunities:
+            print(f"    opportunity: {opportunity.question()}")
+
+
+def _consent(args: argparse.Namespace) -> int:
+    """Import or check the consent cookie that lets an EU address see results.
+
+    Nothing here fabricates a consent value. You answer Google's dialog in your own
+    browser; this reuses that answer, which is also why "reject all" works fine.
+    """
+    jar = CookieJar.load()
+    here = HttpTransport().detect_egress_country()
+
+    if args.import_cookie:
+        try:
+            name, value = parse_cookie(args.import_cookie)
+        except NotAConsentCookie as exc:
+            print(f"refused: {exc}")
+            return 2
+        jar.set("google.com", name, value, captured_egress=args.captured_from or here)
+        jar.save()
+        print(f"stored {name} for google.com in {jar.path} (0600)")
+        print(f"  captured from: {args.captured_from or here or 'unknown'}")
+        print("  (capture from a logged-out private window — a cookie taken from a")
+        print("   signed-in browser shares a token with your account's session)")
+
+    cookies, problems = jar.usable_for("google.com", egress=here)
+    for problem in problems:
+        print(f"  warning: {problem}")
+    if not cookies:
+        print(
+            "no consent cookie stored.\n"
+            "  In your browser: open google.com, DevTools -> Application -> Cookies,\n"
+            "  copy the value of SOCS, then:\n"
+            '    layover consent --import "SOCS=<value>"\n'
+            "  (Answer the dialog however you like — a rejection works too.)"
+        )
+        return 1
+
+    if not cookies:
+        return 1
+    transport = HttpTransport(cookies=cookies, egress_country=here)
+    query = GoogleFlightsOracle().canary_query()
+    result = GoogleFlightsOracle(transport=transport).search(query)
+    age = jar.age_days("google.com")
+    print(
+        f"  cookies: {', '.join(sorted(cookies))}"
+        + (f" (imported {age}d ago)" if age is not None else "")
+    )
+    print(f"  egress:  {here or 'unknown'} (EU: {is_eu_egress(here)})")
+    print(f"  canary {query.describe()}: {result.status}")
+    if result.ok:
+        print(f"  -> {len(result.offers)} offers. The wall is cleared from this address.")
+        return 0
+    print(f"  -> {result.detail[:200]}")
+    return 1
+
+
+def _compare_pos(args: argparse.Namespace) -> int:
+    """Ask the same question from several storefronts and report whether it matters.
+
+    **What this can and cannot show.** Google Flights is metasearch: it displays
+    fares, it does not sell them, so its `gl` parameter is a display setting rather
+    than a point of sale. Real POS pricing — airlines file fares with point-of-sale
+    conditions, so the same seat sits in different buckets per market — happens where
+    a transaction completes, and has to be measured at a seller (Kiwi, AZair, an
+    airline's own country site). A null result here means "this parameter is
+    display-only", never "point of sale does not matter".
+
+    The A/B/A ordering is the part that makes any of it a measurement: prices move on
+    their own, so the baseline is asked twice and any gap smaller than the observed
+    drift is reported as inconclusive rather than as a finding.
+    """
+    intent = load_intent(Path(args.intent))
+    depart, back = intent.date_pairs()[0]
+    target = intent.normalize_currency
+    rates = RateCache(default_cache_path()).get()
+    here = HttpTransport().detect_egress_country()
+    cookies, _ = CookieJar.load().usable_for("google.com", egress=here)
+
+    markets = [m.strip() for m in args.markets.split(",") if m.strip()]
+    currency = args.currency
+
+    def run(market: str) -> dict[tuple, float]:
+        pos = POSContext(currency=currency, locale="en-US", site_market=market)
+        query = OracleQuery(
+            origin=intent.origins[0].code,
+            destination=intent.destinations[0].code,
+            depart=depart,
+            trip_shape=intent.trip_shape,
+            return_on=back if intent.trip_shape is TripShape.RETURN else None,
+            cabin=intent.cabin,
+            pos=pos,
+        )
+        transport = HttpTransport(pos=pos, cookies=cookies, egress_country=here)
+        result = GoogleFlightsOracle(transport=transport).search(query)
+        if not result.ok:
+            print(f"  gl={market:<4} {result.status}: {result.detail[:90]}")
+            return {}
+        prices: dict[tuple, float] = {}
+        for offer in result.offers:
+            normalized = (
+                rates.try_convert(offer.price.amount, offer.price.currency, target)
+                if rates
+                else None
+            )
+            if normalized is None:
+                continue
+            prices[
+                (
+                    offer.segments[0].carrier,
+                    offer.segments[0].depart.strftime("%H:%M"),
+                    len(offer.segments),
+                )
+            ] = normalized
+        print(f"  gl={market:<4} curr={currency}  {len(prices)} comparable offers")
+        return prices
+
+    print(
+        f"exit: {here or 'unknown'}   route: {intent.origins[0].code}-"
+        f"{intent.destinations[0].code} {depart}"
+    )
+    baseline_market = markets[0]
+    first = run(baseline_market)
+    others = {market: run(market) for market in markets[1:]}
+    again = run(baseline_market)  # the same question, last — to measure drift
+
+    drift = _median_gap(first, again)
+    print(f"\n  drift between two identical requests: {drift:+.2%}")
+    floor = max(args.noise, abs(drift) * 2)
+    print(f"  anything under {floor:.1%} is noise, not a finding\n")
+
+    for market, prices in others.items():
+        gap = _median_gap(first, prices)
+        shared = len(set(first) & set(prices))
+        if not shared:
+            print(f"    gl={market:<4} no itineraries in common — inconclusive")
+        elif abs(gap) < floor:
+            print(f"    gl={market:<4} {shared:>2} shared, {gap:+.2%} — display-only")
+        else:
+            print(f"    gl={market:<4} {shared:>2} shared, {gap:+.2%} — DIFFERENT, probe it")
+
+    print(
+        "\n  Remember what this measures: a metasearch page's display parameter.\n"
+        "  Point-of-sale *pricing* is real (airlines file fares per market) but lives\n"
+        "  where a booking completes — measure it at Kiwi, AZair or an airline site."
+    )
+    return 0
+
+
+def _median_gap(a: dict[tuple, float], b: dict[tuple, float]) -> float:
+    """Median relative difference over itineraries both runs returned."""
+    shared = sorted(set(a) & set(b))
+    if not shared:
+        return 0.0
+    gaps = sorted((b[k] - a[k]) / a[k] for k in shared if a[k])
+    return gaps[len(gaps) // 2] if gaps else 0.0
+
+
+def _capture(args: argparse.Namespace) -> int:
+    """Wait for an exit to come up, take a measurement, write it down, exit.
+
+    This exists because of a plain practical constraint: a full-tunnel VPN takes the
+    whole machine with it, so you cannot be on the exit you want to measure *and* be
+    talking to whoever asked for the measurement. So the process waits, notices the
+    exit appear, does its work unattended, and leaves a file behind.
+
+    Two runs of the same query, back to back, so the file carries its own drift
+    figure — a later comparison against another exit can then say whether a gap is an
+    exit effect or just prices moving.
+    """
+    intent = load_intent(Path(args.intent))
+    depart, back = intent.date_pairs()[0]
+    target = intent.normalize_currency
+    out_dir = Path(args.out)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    print(f"waiting for an exit (up to {args.timeout:.0f}s) — bring the VPN up now")
+    deadline = time.monotonic() + args.timeout
+    detected = None
+    while time.monotonic() < deadline:
+        detected = HttpTransport().detect_egress()
+        if args.wait_for:
+            if detected.country and args.wait_for.lower() in detected.country.lower():
+                break
+        elif is_eu_egress(detected.country) is False:
+            break
+        print(f"  still {detected.country or 'unknown'} …")
+        time.sleep(args.poll)
+    else:
+        country = detected.country if detected else "unknown"
+        print(f"  gave up: still {country}. Nothing captured.")
+        return 1
+
+    egress = detected.country
+    refusal = check_egress(detected.country)
+    if refusal:
+        # A capture is a measurement *of the exit*; without one there is nothing to
+        # measure and a file would only mislead whoever compares it later.
+        print(f"  refusing to capture: {refusal}")
+        return 1
+    print(f"  exit is {detected.describe()}. Measuring.")
+    if not detected.verified:
+        print("  NOTE: the exit is not cross-checked — treat any comparison as weaker.")
+    rates = RateCache(default_cache_path()).get()
+    pos = POSContext(currency=target, locale="en-US", site_market=args.market)
+    query = OracleQuery(
+        origin=intent.origins[0].code,
+        destination=intent.destinations[0].code,
+        depart=depart,
+        trip_shape=intent.trip_shape,
+        return_on=back if intent.trip_shape is TripShape.RETURN else None,
+        cabin=intent.cabin,
+        pos=pos,
+    )
+
+    runs = []
+    for index in range(2):  # the same question twice: its own drift control
+        transport = HttpTransport(pos=pos, egress_country=egress)
+        result = GoogleFlightsOracle(transport=transport).search(query)
+        prices = {}
+        if result.ok:
+            for offer in result.offers:
+                normalized = (
+                    rates.try_convert(offer.price.amount, offer.price.currency, target)
+                    if rates
+                    else None
+                )
+                if normalized is None:
+                    continue
+                key = "|".join(
+                    [
+                        offer.segments[0].carrier,
+                        offer.segments[0].depart.strftime("%m-%d %H:%M"),
+                        str(len(offer.segments)),
+                    ]
+                )
+                prices[key] = round(normalized, 2)
+        runs.append(
+            {
+                "at": datetime.now().isoformat(timespec="seconds"),
+                "status": result.status,
+                "detail": result.detail[:200],
+                "prices": prices,
+            }
+        )
+        print(f"  run {index + 1}: {result.status}, {len(prices)} priced itineraries")
+        if index == 0:
+            time.sleep(args.gap)
+
+    capture = {
+        "egress": egress,
+        "egress_ip": detected.ip,
+        "egress_verified": detected.verified,
+        "egress_sources": [
+            {"url": url, "country": country, "ip": ip} for url, country, ip in detected.sources
+        ],
+        "eu": is_eu_egress(egress),
+        "query": query.describe(),
+        "currency": target,
+        "market_param": args.market,
+        "rates_as_of": str(rates.as_of) if rates else None,
+        "runs": runs,
+    }
+    label = args.label or (egress or "unknown").lower().replace(" ", "-")
+    path = out_dir / f"{label}-{datetime.now():%Y%m%d-%H%M%S}.json"
+    path.write_text(json.dumps(capture, indent=2, sort_keys=True))
+    print(f"  wrote {path}")
+    print("  you can drop the VPN now.")
+    return 0
+
+
+def _compare_captures(args: argparse.Namespace) -> int:
+    """Compare two captures taken from different exits.
+
+    Reports a gap only when it is larger than the drift each capture measured on
+    itself. Prices move on their own; without that control this comparison would
+    manufacture findings.
+    """
+    a = json.loads(Path(args.first).read_text())
+    b = json.loads(Path(args.second).read_text())
+
+    def drift_of(capture) -> float:
+        runs = capture["runs"]
+        if len(runs) < 2:
+            return 0.0
+        return _median_gap_str(runs[0]["prices"], runs[1]["prices"])
+
+    a_prices, b_prices = a["runs"][0]["prices"], b["runs"][0]["prices"]
+    shared = sorted(set(a_prices) & set(b_prices))
+    drift = max(abs(drift_of(a)), abs(drift_of(b)))
+    floor = max(args.noise, drift * 2)
+
+    def label(capture) -> str:
+        mark = "" if capture.get("egress_verified") else " [egress unverified]"
+        ip = f", {capture['egress_ip']}" if capture.get("egress_ip") else ""
+        return f"{capture['egress']}{ip}{mark} ({capture['runs'][0]['at']})"
+
+    print(f"  {label(a)}\n  vs {label(b)}")
+    print(f"  query: {a['query']}")
+    if a["query"] != b["query"]:
+        print(f"  WARNING: different queries — {b['query']}")
+    print(f"  self-measured drift: {drift:.2%}; anything under {floor:.1%} is noise\n")
+
+    if not shared:
+        print("  no itineraries in common — inconclusive (schedules or dates differ)")
+        return 1
+    gap = _median_gap_str(a_prices, b_prices)
+    for key in shared[:10]:
+        change = (b_prices[key] - a_prices[key]) / a_prices[key]
+        print(f"    {key:<44} {a_prices[key]:>8.0f} -> {b_prices[key]:>8.0f}  {change:+7.2%}")
+    verdict = (
+        "the exit did not move prices"
+        if abs(gap) < floor
+        else "PRICES DIFFER BY EXIT — the IP is a real POS knob here"
+    )
+    print(f"\n  {len(shared)} shared, median {gap:+.2%}: {verdict}")
+    return 0
+
+
+def _median_gap_str(a: dict[str, float], b: dict[str, float]) -> float:
+    shared = sorted(set(a) & set(b))
+    gaps = sorted((b[k] - a[k]) / a[k] for k in shared if a[k])
+    return gaps[len(gaps) // 2] if gaps else 0.0
+
+
+def _status(args: argparse.Namespace) -> int:
+    root = Path(args.sessions or default_session_root())
+    stores = sorted(root.glob("*.sqlite")) if root.is_dir() else []
+    print(f"session store: {root}  ({len(stores)} session(s))")
+    for path in stores[-5:]:
+        with open_session(path.parent, path.stem) as store:
+            events = store.health_events()
+            print(
+                f"  {path.stem}: {store.query_count()} queries, {len(store.offers())} offers, "
+                f"{len(events)} health event(s), created {store.created_at:%Y-%m-%d %H:%M}"
+            )
+            for event in events[-3:]:
+                print(f"      {event['oracle_id']}: {event['kind']} — {event['detail'][:70]}")
+    return 0
+
+
+def _knowledge(args: argparse.Namespace) -> int:
+    """Show the notebook — the one piece of state that is meant to outlive sessions.
+
+    Worth being able to read, because it is also the thing that will silently stop a
+    search from asking a source. A wrong entry here looks like an oracle that quietly
+    does nothing, which is exactly the failure mode DESIGN §5 says to keep visible.
+    """
+    knowledge = OracleKnowledge(Path(args.path) if args.path else None)
+    if args.forget:
+        dropped = knowledge.forget(args.forget)
+        print(f"forgot {dropped} fact(s) about {args.forget}")
+        return 0
+
+    print(f"knowledge: {knowledge.path}  (coverage facts expire after {knowledge.ttl_days}d)")
+    gaps = knowledge.known_gaps()
+    print(f"  coverage gaps in force ({len(gaps)}):")
+    for fact in gaps:
+        print(f"    {fact.oracle_id:<24} {fact.route:<10} learned {fact.age_days()}d ago")
+    if not gaps:
+        print("    none — every oracle will be asked about every route")
+    for oracle_id in knowledge.oracles():
+        health = knowledge.health(oracle_id)
+        if not health:
+            continue
+        cooling = knowledge.cooling(oracle_id)
+        state = f"cooling until {cooling:%Y-%m-%d %H:%M}" if cooling else "available"
+        fails = health.get("consecutive_failures", 0)
+        last = health.get("last_failure", "—")
+        print(f"  {oracle_id:<24} {state}, {fails} consecutive failure(s), last: {last}")
+    return 0
+
+
+def _gc(args: argparse.Namespace) -> int:
+    removed = gc(Path(args.sessions or default_session_root()), retention_days=args.days)
+    print(f"removed {len(removed)} session(s) older than {args.days} days")
+    for path in removed:
+        print(f"  {path.name}")
+    if not args.all:
+        print("  (reports are user-owned documents and were left alone; --all removes them)")
+    return 0
+
+
+def load_dotenv(paths: list[Path] | None = None) -> list[str]:
+    """Read `KEY=value` lines from a gitignored `.env` (DESIGN §13).
+
+    Secrets come from the environment, never from a config file — but typing
+    `export SERPAPI_KEY=…` into every shell is the kind of friction that ends with
+    someone pasting a key into a TOML. Existing environment variables always win, so
+    a file can never silently override what you set on purpose.
+    """
+    loaded: list[str] = []
+    for path in paths or [Path(".env"), Path.home() / ".config" / "layover" / ".env"]:
+        if not path.is_file():
+            continue
+        for line in path.read_text().splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            name, _, value = line.partition("=")
+            name, value = name.strip(), value.strip().strip("\"'")
+            if name and name not in os.environ:
+                os.environ[name] = value
+                loaded.append(name)
+    return loaded
+
+
+def main(argv: list[str] | None = None) -> int:
+    load_dotenv()
+    parser = argparse.ArgumentParser(prog="layover", description=__doc__.splitlines()[0])
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    search = sub.add_parser("search", help="run one search and rank what comes back")
+    search.add_argument("intent", help="path to an intent TOML file")
+    search.add_argument("--session", help="session id (default: a timestamp)")
+    search.add_argument("--sessions", help="session store directory")
+    search.add_argument("--currency", help="ask the oracle in this currency")
+    search.add_argument("--locale", default="en-US")
+    search.add_argument("--market", default="us")
+    search.add_argument(
+        "--oracle",
+        default="azair",
+        choices=("auto", "azair", "google", "serpapi"),
+        help=(
+            "auto: the cheapest oracle that can answer, shown with its reckoning. "
+            "azair: European sellers, no exit needed. google: displayed fares, needs "
+            "a non-EU exit or a consent cookie. serpapi: paid, one credit per query."
+        ),
+    )
+    search.add_argument(
+        "--max-money",
+        type=float,
+        default=0.0,
+        help="money this search may spend on paid oracles (default 0 = free only)",
+    )
+    search.add_argument(
+        "--serpapi-cap",
+        type=int,
+        default=0,
+        help="monthly credit cap for serpapi (0 = off; the free tier is 250/month)",
+    )
+    search.add_argument("--rows", type=int, default=15, help="rows in the table")
+    search.add_argument("--explain", type=int, default=3, help="itemize the top N rows in full")
+    search.add_argument("--max-stops", type=int, default=1)
+    search.add_argument(
+        "--allow-unknown-exit",
+        action="store_true",
+        help="record prices even when the exit cannot be determined",
+    )
+    search.add_argument(
+        "--no-probe",
+        dest="probe",
+        action="store_false",
+        help="baseline only: skip the return-vs-two-one-ways probe (saves 2 queries)",
+    )
+    search.add_argument(
+        "--recheck-coverage",
+        action="store_true",
+        help="ignore remembered coverage gaps and ask every oracle again",
+    )
+    search.set_defaults(func=_search)
+
+    known = sub.add_parser("knowledge", help="what we remember about the oracles")
+    known.add_argument("--forget", metavar="ORACLE", help="drop everything about one oracle")
+    known.add_argument("--path", help="knowledge file (default: state dir)")
+    known.set_defaults(func=_knowledge)
+
+    consent = sub.add_parser(
+        "consent", help="import/check the Google consent cookie (EU addresses)"
+    )
+    consent.add_argument(
+        "--import", dest="import_cookie", metavar="SOCS=...", help="a consent cookie"
+    )
+    consent.add_argument(
+        "--captured-from",
+        help="exit the cookie was captured from (default: where you are now)",
+    )
+    consent.set_defaults(func=_consent)
+
+    compare = sub.add_parser(
+        "compare-pos", help="does the point of sale actually change the price?"
+    )
+    compare.add_argument("intent")
+    compare.add_argument("--markets", default="us,hu,tr", help="first is the baseline")
+    compare.add_argument("--currency", default="EUR")
+    compare.add_argument("--noise", type=float, default=0.02, help="FX-noise threshold")
+    compare.set_defaults(func=_compare_pos)
+
+    capture = sub.add_parser(
+        "capture", help="wait for a VPN exit, measure unattended, write a file"
+    )
+    capture.add_argument("intent")
+    capture.add_argument("--out", default="captures")
+    capture.add_argument("--wait-for", help="country substring, e.g. Brazil")
+    capture.add_argument("--timeout", type=float, default=300.0)
+    capture.add_argument("--poll", type=float, default=10.0)
+    capture.add_argument("--gap", type=float, default=20.0, help="seconds between runs")
+    capture.add_argument("--market", default="us")
+    capture.add_argument("--label")
+    capture.set_defaults(func=_capture)
+
+    compare_caps = sub.add_parser("compare-captures", help="did the exit change the prices?")
+    compare_caps.add_argument("first")
+    compare_caps.add_argument("second")
+    compare_caps.add_argument("--noise", type=float, default=0.02)
+    compare_caps.set_defaults(func=_compare_captures)
+
+    status = sub.add_parser("status", help="what recent sessions did")
+    status.add_argument("--sessions")
+    status.set_defaults(func=_status)
+
+    collect = sub.add_parser("gc", help="remove aged-out session stores")
+    collect.add_argument("--sessions")
+    collect.add_argument("--days", type=int, default=14)
+    collect.add_argument("--all", action="store_true", help="reports too")
+    collect.set_defaults(func=_gc)
+
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())