layover 0.1.0.dev0__py3-none-any.whl

layover/oracles/api/gf_parse.py

@@ -0,0 +1,344 @@
+"""Parsing a Google Flights results page (ORACLES §3).
+
+Written against a recorded fixture — `tests/fixtures/google_flights/` — and pinned by
+a golden test, so CI re-runs it against real bytes without touching the network.
+
+**Why the accessibility labels rather than the class names.** A results row carries
+its own description for screen readers: *"Leaves Budapest Ferenc Liszt International
+Airport at 8:35 PM on Sunday, October 4 and arrives at Suvarnabhumi Airport at 3:25 PM
+on Monday, October 5"*, *"Layover (1 of 1) is a 2 hr 20 min layover at Istanbul
+Airport"*, *"1002 US dollars"*. Those strings are the site's contract with assistive
+technology; obfuscated class names are its contract with nobody. They churn far less.
+
+**What a row does and does not say.** It states the whole itinerary's price, its
+endpoints, its total duration, and each layover's airport and length. It does *not*
+state flight numbers or per-segment times — those live in the details panel behind a
+second request. Two consequences, both recorded on every offer rather than hidden:
+
+* segment times for connecting itineraries are **interpolated** (flight time split
+  evenly between segments); the layover durations themselves are exact, and they are
+  what the connection logic actually uses;
+* on a round-trip search the price is the **round-trip total** shown against an
+  outbound option, with the inbound not yet chosen. That is what Google means by it,
+  so that is what the offer says.
+"""
+
+from __future__ import annotations
+
+import html as html_module
+import re
+from dataclasses import dataclass, field
+from datetime import UTC, date, datetime, timedelta
+
+from layover.models import Leg, Offer, POSContext, Protection, Segment, TripShape
+from layover.money import Money
+from layover.oracles.base import OracleQuery
+
+_ROW = re.compile(r'<li class="pIav2d"')
+_ARIA = re.compile(r'aria-label="([^"]{4,400})"')
+_NBSP = " "
+
+_LEAVES = re.compile(
+    r"Leaves (?P<from>.+?) at (?P<dep>\d{1,2}:\d{2}\s?(?:AM|PM)) on "
+    r"(?P<dep_day>[A-Za-z]+, [A-Za-z]+ \d{1,2}) and arrives at (?P<to>.+?) at "
+    r"(?P<arr>\d{1,2}:\d{2}\s?(?:AM|PM)) on (?P<arr_day>[A-Za-z]+, [A-Za-z]+ \d{1,2})"
+)
+_PRICE = re.compile(r"^(?P<amount>[\d,]+) (?P<currency>[A-Za-z ]+?)s?$")
+_DURATION = re.compile(r"Total duration (?P<h>\d+) hr(?: (?P<m>\d+) min)?")
+_STOPS = re.compile(r"(?P<n>\d+) stop flight|Nonstop flight")
+_LAYOVER = re.compile(
+    r"Layover \((?P<i>\d+) of (?P<n>\d+)\) is a (?:(?P<h>\d+) hr )?(?:(?P<m>\d+) min )?"
+    r"layover at (?P<airport>.+?)(?: in .+)?\."
+)
+_CODE_CELL = re.compile(r">([A-Z]{3})</(?:span|div)>")
+# "1 stop in IST", "2 stops in WAW, AUH" — the row's own summary of where it stops,
+# in order. Preferred over scraping three-letter cells, which also match airline
+# codes: an early version routed a KLM itinerary "BUD-KLM-BKK".
+_STOPS_IN = re.compile(r"\d+ stops? in ([A-Z]{3}(?:,\s*[A-Z]{3})*)")
+# The row's own summary line, which states carrier and stop count in one place:
+# "From 1065 US dollars round trip total. 1 stop flight with Emirates. Leaves …"
+_SUMMARY = re.compile(
+    r"From (?P<amount>[\d,]+) (?P<currency>[A-Za-z ]+?) (?P<trip>round trip total|total)\. "
+    r"(?:(?P<stops>\d+) stop|Nonstop) flight with (?P<carrier>[^.]+)\."
+)
+
+CURRENCY_WORDS = {
+    "US dollar": "USD",
+    "euro": "EUR",
+    "British pound": "GBP",
+    "Hungarian forint": "HUF",
+    "Turkish lira": "TRY",
+    "Thai baht": "THB",
+    "Indian rupee": "INR",
+    "Swiss franc": "CHF",
+    "Canadian dollar": "CAD",
+    "Australian dollar": "AUD",
+}
+
+
+@dataclass(slots=True)
+class ParsedRow:
+    """Exactly what one results row states — no more, and nothing inferred."""
+
+    price: float | None = None
+    currency: str | None = None
+    carrier: str = ""
+    depart_at: datetime | None = None
+    arrive_at: datetime | None = None
+    total_minutes: int | None = None
+    stops: int | None = None
+    layovers: list[tuple[str, int]] = field(default_factory=list)
+    """(airport code or name, minutes) in order."""
+    airport_codes: list[str] = field(default_factory=list)
+    stop_codes: list[str] = field(default_factory=list)
+    """Intermediate airports, in order, as the row itself lists them."""
+    round_trip_total: bool = False
+    """Google prices a round trip against its outbound half; the row says which."""
+    labels: list[str] = field(default_factory=list)
+
+    @property
+    def usable(self) -> bool:
+        return None not in (self.price, self.depart_at, self.arrive_at)
+
+
+def _clean(text: str) -> str:
+    return html_module.unescape(text).replace(_NBSP, " ").replace("\xa0", " ").strip()
+
+
+def _parse_clock(value: str, day_text: str, year: int) -> datetime | None:
+    """ "8:35 PM" + "Sunday, October 4" -> a datetime, given the search year.
+
+    Google omits the year, so it comes from the query. A December search that lands
+    in January would be off by a year, which is why the caller passes the departure
+    date rather than "now".
+
+    **On timezones.** These are *local* clock times at each airport, and mapping them
+    to instants needs an airport timezone table (OurAirports, DESIGN §13 — M1 work).
+    Until then the local clock is preserved and labelled UTC, and arrival instants are
+    derived from the row's stated total duration rather than from clock arithmetic —
+    so elapsed time, layover lengths and departure-hour effects are all correct, and
+    only the arrival's *local* hour is unrepresented. Every offer says so.
+    """
+    try:
+        month_day = day_text.split(",", 1)[1].strip()
+        stamp = datetime.strptime(f"{month_day} {year} {value}", "%B %d %Y %I:%M %p")
+    except (ValueError, IndexError):
+        return None
+    return stamp.replace(tzinfo=UTC)
+
+
+def parse_rows(html: str, *, year: int) -> list[ParsedRow]:
+    """Split the page into rows and read each one's labels."""
+    starts = [m.start() for m in _ROW.finditer(html)]
+    rows: list[ParsedRow] = []
+    for index, start in enumerate(starts):
+        end = starts[index + 1] if index + 1 < len(starts) else min(len(html), start + 20000)
+        rows.append(_parse_row(html[start:end], year=year))
+    return rows
+
+
+def _parse_row(chunk: str, *, year: int) -> ParsedRow:
+    row = ParsedRow()
+    row.labels = [_clean(label) for label in _ARIA.findall(chunk)]
+
+    for label in row.labels:
+        if match := _SUMMARY.search(label):
+            # Preferred: one label states price, stop count and carrier together.
+            row.price = float(match["amount"].replace(",", ""))
+            word = match["currency"].strip()
+            row.currency = CURRENCY_WORDS.get(word, CURRENCY_WORDS.get(word.rstrip("s"), word))
+            row.stops = int(match["stops"]) if match["stops"] else 0
+            row.carrier = _clean(match["carrier"])
+            row.round_trip_total = match["trip"] == "round trip total"
+        if (match := _LEAVES.search(label)) and row.depart_at is None:
+            row.depart_at = _parse_clock(match["dep"], match["dep_day"], year)
+            row.arrive_at = _parse_clock(match["arr"], match["arr_day"], year)
+        elif (match := _PRICE.match(label)) and row.price is None:
+            word = match["currency"].strip()
+            row.price = float(match["amount"].replace(",", ""))
+            row.currency = CURRENCY_WORDS.get(word, CURRENCY_WORDS.get(word.rstrip("s"), word))
+        elif match := _DURATION.search(label):
+            row.total_minutes = int(match["h"]) * 60 + int(match["m"] or 0)
+        elif match := _STOPS.search(label):
+            row.stops = int(match["n"]) if match["n"] else 0
+        elif match := _LAYOVER.search(label):
+            minutes = int(match["h"] or 0) * 60 + int(match["m"] or 0)
+            row.layovers.append((_clean(match["airport"]), minutes))
+
+    stops_in = _STOPS_IN.search(chunk)
+    if stops_in:
+        row.stop_codes = [code.strip() for code in stops_in.group(1).split(",")]
+    row.airport_codes = list(dict.fromkeys(_CODE_CELL.findall(chunk)))
+    if not row.carrier:
+        fallback = re.search(
+            r">([A-Z][A-Za-z\' ]{3,30}(?:Airlines|Airways|Air|Jet|KLM))<", chunk
+        )
+        if fallback:
+            row.carrier = _clean(fallback.group(1))
+    return row
+
+
+# ── rows to offers ───────────────────────────────────────────────────────────
+
+
+def _airport_code(name_or_code: str, known: list[str]) -> str:
+    """Map "Istanbul Airport" to IST when the row's code cells make it obvious."""
+    if len(name_or_code) == 3 and name_or_code.isupper():
+        return name_or_code
+    for code in known:
+        if code[0] == name_or_code[0].upper():
+            return code
+    return name_or_code[:3].upper()
+
+
+def _segments(row: ParsedRow, query: OracleQuery) -> list[Segment]:
+    """Build the segment chain, exact where the row is exact.
+
+    What the row states exactly: the departure clock time, the total duration, and
+    each layover's airport and length. What it does not state: per-segment times. So
+    flying time (total minus layovers) is split evenly between segments — an
+    approximation that moves nothing the connection logic depends on, since the gaps
+    themselves are exact. Offers built this way carry a note saying so.
+    """
+    if row.depart_at is None:
+        return []
+
+    total = row.total_minutes
+    if total is None and row.arrive_at is not None:
+        total = int((row.arrive_at - row.depart_at).total_seconds() / 60)
+    if not total or total <= 0:
+        return []
+
+    codes = row.stop_codes or [
+        code
+        for code in row.airport_codes
+        if code not in {query.origin.upper(), query.destination.upper()}
+    ]
+    # The stop list is authoritative when it disagrees with the summary label.
+    stops = len(codes) if codes else (row.stops if row.stops is not None else 0)
+    depart = row.depart_at
+
+    if stops == 0 or not row.layovers:
+        return [
+            Segment(
+                carrier=row.carrier or "??",
+                flight_number="",
+                origin=query.origin,
+                destination=query.destination,
+                depart=depart,
+                arrive=depart + timedelta(minutes=total),
+                cabin=query.cabin,
+            )
+        ]
+
+    layover_total = sum(minutes for _, minutes in row.layovers)
+    flying = max(30.0, total - layover_total)
+    per_segment = flying / (stops + 1)
+
+    points = [query.origin]
+    for index in range(stops):
+        if index < len(codes):
+            points.append(codes[index])
+        elif index < len(row.layovers):
+            points.append(_airport_code(row.layovers[index][0], codes))
+        else:  # pragma: no cover — a stop with neither a code nor a label
+            points.append("???")
+    points.append(query.destination)
+
+    layover_minutes = [minutes for _, minutes in row.layovers]
+    segments: list[Segment] = []
+    cursor = depart
+    for index in range(len(points) - 1):
+        arrive = cursor + timedelta(minutes=per_segment)
+        segments.append(
+            Segment(
+                carrier=row.carrier or "??",
+                flight_number="",
+                origin=points[index],
+                destination=points[index + 1],
+                depart=cursor,
+                arrive=arrive,
+                cabin=query.cabin,
+            )
+        )
+        if index < len(layover_minutes):
+            cursor = arrive + timedelta(minutes=layover_minutes[index])
+        else:
+            cursor = arrive
+    return segments
+
+
+def row_to_offer(
+    row: ParsedRow,
+    query: OracleQuery,
+    *,
+    oracle_id: str = "google_flights",
+    pos: POSContext | None = None,
+) -> Offer | None:
+    if not row.usable:
+        return None
+    segments = _segments(row, query)
+    if not segments:
+        return None
+
+    pos = pos or query.pos
+    notes = [
+        "google-flights row: flight numbers not shown at row level",
+        "local clock times labelled UTC; arrival derived from stated duration "
+        "(needs an airport timezone table)",
+    ]
+    if len(segments) > 1:
+        notes.append("segment times interpolated; layover durations are exact")
+    if row.round_trip_total or query.trip_shape is TripShape.RETURN:
+        notes.append("round-trip total priced against this outbound; inbound not yet chosen")
+    if row.currency and pos.currency and row.currency != pos.currency:
+        notes.append(f"row currency {row.currency} differs from requested {pos.currency}")
+
+    return Offer(
+        legs=[Leg(segments=segments)],
+        price=Money(amount=row.price, currency=row.currency or pos.currency),
+        protection=Protection.SINGLE_TICKET,
+        pos=pos,
+        oracle_id=oracle_id,
+        observed_at=datetime.now(UTC),
+        fare_notes=notes,
+    )
+
+
+def parse_page(
+    html: str,
+    query: OracleQuery,
+    *,
+    oracle_id: str = "google_flights",
+    pos: POSContext | None = None,
+    year: int | None = None,
+) -> list[Offer]:
+    """The adapter's entry point: a results page in, normalized offers out."""
+    search_year = year or (query.depart or date.today()).year
+    offers: list[Offer] = []
+    seen: set[tuple] = set()
+    for row in parse_rows(html, year=search_year):
+        offer = row_to_offer(row, query, oracle_id=oracle_id, pos=pos)
+        if offer is None:
+            continue
+        # Google lists the same itinerary twice — once under "best flights", once
+        # under "other flights". Two rows, one product: counting both would flatter
+        # every routing that appears in both sections.
+        #
+        # NOT `offer.identity_key` here: that keys on flight numbers, which a results
+        # row does not carry, so two different Turkish itineraries on the same date
+        # would collide. Clock times and price distinguish them; this is a
+        # within-page dedup, and cross-oracle identity still needs flight numbers
+        # from the details panel (verification, DESIGN §6).
+        segments = offer.segments
+        key = (
+            offer.price.amount,
+            tuple((s.carrier, s.origin, s.destination) for s in segments),
+            segments[0].depart,
+            segments[-1].arrive,
+        )
+        if key in seen:
+            continue
+        seen.add(key)
+        offers.append(offer)
+    return offers

layover/oracles/api/google_flights.py

@@ -0,0 +1,322 @@
+"""Google Flights via the `tfs` protobuf URL (ORACLES §4).
+
+The M0 keystone: broad coverage, calendar pricing, and cheap enough to be the source
+of the bounds the solver prunes with. It is also an undocumented internal encoding on
+a consumer page, which is stated plainly in ORACLES §7 rather than glossed — and the
+reason `google_flights_browser` exists as a peer rather than a someday.
+
+**Status of this adapter.** Both halves are verified against real output. The encoder
+produces a `tfs` Google parses; the parser is written against a recorded fixture
+(`tests/fixtures/google_flights/`) and pinned by a golden test that runs offline.
+
+One thing to know before trusting a result: **from an EU address every request lands
+on `consent.google.com`**, which this adapter reports as `FailureKind.BLOCKED` with
+what to do about it, rather than pretending to have searched. The fixture above was
+captured through a non-EU exit — which also means it is a *US* point of sale, and the
+offers say so. Getting home-market prices from a Hungarian IP needs a browser profile
+that has answered the consent dialog (ORACLES §2); that is still the browser oracle's
+job, and this adapter cannot do it.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+from datetime import date
+from typing import Any
+
+from layover.models import Cabin, Offer, POSContext, TripShape
+from layover.oracles.api.gf_parse import parse_page
+from layover.oracles.api.protobuf import Message
+from layover.oracles.base import (
+    FailureKind,
+    Oracle,
+    OracleCapabilities,
+    OracleQuery,
+    QueryResult,
+)
+from layover.oracles.transport import HttpTransport, is_eu_egress
+
+BASE_URL = "https://www.google.com/travel/flights"
+
+# Enum values in the tfs schema. Not published anywhere; derived from the encoding
+# and confirmed by Google accepting the result. Wrong values here produce a *valid*
+# query for the wrong thing, which is why the tests pin them.
+SEAT = {Cabin.ECONOMY: 1, Cabin.PREMIUM: 2, Cabin.BUSINESS: 3}
+TRIP = {TripShape.RETURN: 1, TripShape.ONE_WAY: 2, TripShape.MULTI_CITY: 3}
+PASSENGER_ADULT = 1
+
+_FIELD_DATE = 2
+_FIELD_FROM = 13
+_FIELD_TO = 14
+_FIELD_MAX_STOPS = 5
+_FIELD_LEGS = 3
+_FIELD_PASSENGERS = 8
+_FIELD_SEAT = 9
+_FIELD_TRIP = 19
+
+
+def _airport(code: str) -> Message:
+    return Message().string(2, code.upper())
+
+
+def _leg(origin: str, destination: str, day: date, max_stops: int | None) -> Message:
+    return (
+        Message()
+        .string(_FIELD_DATE, day.isoformat())
+        .varint(_FIELD_MAX_STOPS, max_stops)
+        .message(_FIELD_FROM, _airport(origin))
+        .message(_FIELD_TO, _airport(destination))
+    )
+
+
+def build_tfs(query: OracleQuery) -> str:
+    """Encode a query as the base64url protobuf Google expects.
+
+    A return trip is two legs in one message — not two queries — which is what lets a
+    single request price a round trip the way the site does.
+    """
+    info = Message()
+    info.message(
+        _FIELD_LEGS, _leg(query.origin, query.destination, query.depart, query.max_stops)
+    )
+    if query.trip_shape is TripShape.RETURN:
+        if query.return_on is None:  # pragma: no cover — OracleQuery validates this
+            raise ValueError("return query without a return date")
+        info.message(
+            _FIELD_LEGS,
+            _leg(query.destination, query.origin, query.return_on, query.max_stops),
+        )
+    for _ in range(query.adults):
+        info.varint(_FIELD_PASSENGERS, PASSENGER_ADULT)
+    info.varint(_FIELD_SEAT, SEAT.get(query.cabin, 1))
+    info.varint(_FIELD_TRIP, TRIP.get(query.trip_shape, 2))
+    return info.to_base64()
+
+
+def build_url(query: OracleQuery) -> str:
+    """The full search URL, including the point-of-sale parameters (§9).
+
+    Three knobs, and measurement rather than assumption about what each does — the
+    POS layer's whole job is knowing which one actually moves a given site's prices:
+
+    * `curr` **does** the work. Ask in the currency you want to compare in, because
+      Google's own conversion and a later ECB conversion are not the same number, and
+      double-converting adds noise to every comparison.
+    * `gl` (the storefront market) **made no difference at all**: `gl=hu` and `gl=us`
+      returned byte-identical prices (198/234/250/266/393 EUR) for the same query from
+      the same exit, measured 2026-08-05. Recorded in ORACLES §4 so nobody spends
+      query budget probing it again.
+    * `hl` is **forced to English**, and is not a POS knob here. It only sets the UI
+      language, and the parser reads English accessibility labels — a Hungarian page
+      parses to zero offers, which is exactly the `empty_anomaly` that revealed this.
+      Language and market are separate things and are kept separate.
+    """
+    pos: POSContext = query.pos
+    market = (pos.site_market or pos.ip_country or "us").lower()
+    params = [
+        f"tfs={build_tfs(query)}",
+        f"curr={pos.currency}",
+        "hl=en",
+        f"gl={market}",
+    ]
+    return f"{BASE_URL}?{'&'.join(params)}"
+
+
+# ── response handling ────────────────────────────────────────────────────────
+
+_CONSENT_MARKERS = ("consent.google.com", "Before you continue", "consent.youtube.com")
+_BLOCK_MARKERS = ("Our systems have detected unusual traffic", "/sorry/index")
+
+
+def classify_response(status_code: int, url: str, body: str) -> FailureKind | None:
+    """Decide what a response actually is, before trying to parse it.
+
+    The distinction that matters: a consent wall and a bot wall are both "no results",
+    but the first is fixed by a browser profile that has answered the dialog and the
+    second means back off. Treating either as an empty market would be a lie the
+    health monitor then acts on.
+    """
+    if status_code == 429:
+        return FailureKind.RATE_LIMITED
+    if status_code in (403, 451):
+        return FailureKind.BLOCKED
+    if status_code >= 500:
+        return FailureKind.TIMEOUT
+    haystack = f"{url}\n{body[:4000]}"
+    if any(marker in haystack for marker in _CONSENT_MARKERS):
+        return FailureKind.BLOCKED
+    if any(marker in haystack for marker in _BLOCK_MARKERS):
+        return FailureKind.BLOCKED
+    return None
+
+
+_CALLBACK = re.compile(r"AF_initDataCallback\(")
+
+
+def _balanced_slice(text: str, start: int) -> str | None:
+    """The JSON value beginning at `start`, found by counting brackets.
+
+    A regex cannot do this: the payload contains nested arrays, quoted brackets and no
+    terminator of its own. Counting is boring and correct.
+    """
+    opener = text[start]
+    closer = {"[": "]", "{": "}"}.get(opener)
+    if closer is None:
+        return None
+    depth = 0
+    in_string = False
+    escaped = False
+    for index in range(start, len(text)):
+        char = text[index]
+        if in_string:
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == '"':
+                in_string = False
+            continue
+        if char == '"':
+            in_string = True
+        elif char == opener:
+            depth += 1
+        elif char == closer:
+            depth -= 1
+            if depth == 0:
+                return text[start : index + 1]
+    return None
+
+
+def extract_data_blobs(html: str) -> list[Any]:
+    """The page's embedded state, from its `AF_initDataCallback` calls.
+
+    Not used for itineraries — those are server-rendered into the rows and read from
+    their accessibility labels (`gf_parse`). Kept because the blobs carry the
+    currency, market and locale tables the POS layer will want (§9), and because the
+    first thing to check when the parser breaks is whether the page still ships them.
+    """
+    blobs: list[Any] = []
+    for match in _CALLBACK.finditer(html):
+        marker = html.find("data:", match.end())
+        if marker == -1:
+            continue
+        index = marker + len("data:")
+        while index < len(html) and html[index] in " \t\r\n":
+            index += 1
+        if index >= len(html):
+            continue
+        payload = _balanced_slice(html, index)
+        if payload is None:
+            continue
+        try:
+            blobs.append(json.loads(payload))
+        except json.JSONDecodeError:
+            continue
+    return blobs
+
+
+def parse_offers(
+    html: str,
+    query: OracleQuery,
+    *,
+    oracle_id: str = "google_flights",
+    pos: POSContext | None = None,
+) -> list[Offer]:
+    """Turn a results page into normalized offers (see `gf_parse` for the how)."""
+    return parse_page(html, query, oracle_id=oracle_id, pos=pos)
+
+
+class GoogleFlightsOracle(Oracle):
+    """The protobuf-URL adapter."""
+
+    id = "google_flights"
+    capabilities = OracleCapabilities(
+        trip_shapes=frozenset({TripShape.ONE_WAY, TripShape.RETURN}),
+        date_range_query=False,
+        nearby_airports=False,
+        baggage_filter=False,
+        pos_controls=frozenset({"market_param", "currency_param", "locale"}),
+        latency_est_s=2.0,
+        block_risk="low",
+        money_cost_per_query=0.0,
+        bookable="deep_link",
+    )
+
+    def __init__(
+        self,
+        *,
+        client: Any | None = None,
+        transport: HttpTransport | None = None,
+        timeout: float = 20.0,
+    ) -> None:
+        self._client = client
+        self._transport = transport
+        self._timeout = timeout
+
+    def _get(self, url: str) -> tuple[int, str, str]:
+        if self._client is not None:  # test double
+            response = self._client.get(url, follow_redirects=True)
+            return response.status_code, str(response.url), response.text
+        transport = self._transport or HttpTransport(timeout=self._timeout)
+        response = transport.get(url)
+        return response.status_code, response.url, response.text
+
+    def search(self, query: OracleQuery) -> QueryResult:
+        if not self.capabilities.can_answer(query):
+            return QueryResult.failed(
+                query, self.id, FailureKind.UNSUPPORTED, f"cannot do {query.trip_shape}"
+            )
+
+        url = build_url(query)
+        started = time.monotonic()
+        try:
+            status, final_url, body = self._get(url)
+        except Exception as exc:
+            return QueryResult.failed(
+                query,
+                self.id,
+                FailureKind.TIMEOUT,
+                f"{type(exc).__name__}: {exc}",
+                latency_ms=(time.monotonic() - started) * 1000,
+            )
+        latency_ms = (time.monotonic() - started) * 1000
+
+        failure = classify_response(status, final_url, body)
+        if failure is not None:
+            detail = f"HTTP {status} at {final_url[:120]}"
+            if "consent" in final_url:
+                egress = self._transport.egress_country if self._transport else None
+                where = f" (egress: {egress})" if egress else ""
+                detail += f" — consent wall{where}. "
+                detail += (
+                    "Expected from an EU exit: leave the EU (a VPN exit, or a "
+                    "`pos.toml` proxy) or use a browser profile that has answered "
+                    "the dialog (ORACLES §2, §6)."
+                    if is_eu_egress(egress) is not False
+                    else "Unexpected from a non-EU exit — the page may have changed."
+                )
+            return QueryResult.failed(query, self.id, failure, detail, latency_ms=latency_ms)
+
+        observed_pos = (
+            self._transport.pos_with_egress() if self._transport is not None else query.pos
+        )
+        offers = parse_offers(body, query, oracle_id=self.id, pos=observed_pos)
+        if not offers:
+            # Never "no flights": either the market is empty or we are broken, and on
+            # a route with any liquidity it is us.
+            return QueryResult.failed(
+                query,
+                self.id,
+                FailureKind.EMPTY_ANOMALY,
+                "no itineraries parsed from a 200 response",
+                latency_ms=latency_ms,
+            )
+        return QueryResult(
+            query=query,
+            oracle_id=self.id,
+            offers=offers,
+            latency_ms=latency_ms,
+            raw=body,
+        )