Bug hunt round 2: statement parsing, offer gating, geo scope, flight backend

app/card_catalogue.py

@@ -48,6 +48,12 @@ class Card:
     point_value_inr: float
     base_rate: float                  # reward units per INR 100
     kind: str = "credit"              # "credit" | "debit" - debit cards join the best-card reco, not "apply for"
+    # Closed to NEW applicants. Still scored for holders, never suggested as a
+    # discovery. The field did not exist here at all, so the server happily told
+    # people to apply for Axis Atlas (closed since Sep 2025) while the app,
+    # which has always carried the flag, recommended something they could
+    # actually get. Mirror of cards.ts `closed`.
+    closed: bool = False
     category_rates: Dict[str, float] = field(default_factory=dict)
     caps: Dict[str, Optional[int]] = field(default_factory=dict)  # per-category monthly cap (reward units)
     cap_groups: List[Dict] = field(default_factory=list)  # [{"categories": [...], "cap": N}] shared monthly cap
@@ -2016,3 +2022,20 @@ def is_likely_eligible(card_id: str, band) -> bool:
     if not band or band not in INCOME_BAND_CEILING:
         return True
     return CARD_MIN_INCOME_INR.get(card_id, 0) < INCOME_BAND_CEILING[band]
+
+
+# The 7 cards cards.ts marks `closed: true`. Applied after construction so the
+# per-card literals above stay untouched and the two lists cannot drift apart
+# silently - tests/parity assert this set matches cards.ts exactly.
+CLOSED_TO_NEW_APPLICANTS = {
+    "amex_mrcc",
+    "amex_platinum_travel",
+    "axis_atlas",
+    "hdfc_regalia",
+    "kotak_mojo",
+    "kotak_myntra",
+    "kotak_royale",
+}
+for _c in CATALOGUE:
+    if _c.id in CLOSED_TO_NEW_APPLICANTS:
+        _c.closed = True

app/channels.py

@@ -227,17 +227,48 @@ FUEL_CHANNELS = [
 ]
 
 # Issuer portal booking sites (behind login; the portal decides final routing).
+# EVERY portal_name in the card catalogue must appear here, or that portal
+# wins a row and the tile renders no Book button - the same "booking links are
+# absent" bug as the OTA rows, arriving through a different door. Mirror of
+# channels.ts PORTAL_URLS; app/scripts/booklink_regress.ts asserts coverage.
 PORTAL_URLS = {
     "HDFC SmartBuy": "https://offers.smartbuy.hdfcbank.com",
+    # Four HDFC cards spell it without the issuer prefix. Same portal, and
+    # PORTAL_KEYS collapses both spellings onto one channel key.
+    "SmartBuy": "https://offers.smartbuy.hdfcbank.com",
     "Axis Travel Edge": "https://traveledge.axisbank.co.in",
     "ICICI iShop": "https://ishop.icicibank.com",
+    "HSBC Rewards Marketplace": "https://rewards.hsbc.co.in",
+    "Scapia app (flights/hotels/buses/trains)": "https://www.scapia.cards",
+    # Amex India's rewards hub. Reward Multiplier has no standalone domain
+    # (rewardmultiplier.in does not resolve), so this is the issuer page the
+    # redemption actually lives behind - never a broken link.
+    "Reward Multiplier": "https://www.americanexpress.com/in/rewards/",
 }
 
 # Issuer booking portals (HDFC SmartBuy, Axis Travel Edge, ICICI iShop) are a
 # further channel: elevated portal-only rates, but only for holders of that
 # issuer's portal-rated cards, capped monthly, paid in points (assumed redeemed
 # at the portal point value). Synthesized per wallet, pan-India online.
-PORTAL_KEYS = {"HDFC SmartBuy": "smartbuy", "Axis Travel Edge": "travel_edge", "ICICI iShop": "ishop"}
+PORTAL_KEYS = {
+    "HDFC SmartBuy": "smartbuy", "SmartBuy": "smartbuy",
+    "Axis Travel Edge": "travel_edge", "ICICI iShop": "ishop",
+    "HSBC Rewards Marketplace": "hsbc_rewards", "Reward Multiplier": "amex_rewards",
+    "Scapia app (flights/hotels/buses/trains)": "scapia",
+}
+
+# What we DISPLAY for a portal key. Grouping by key (not by the raw string) is
+# what stops "HDFC SmartBuy" and "SmartBuy" - the same portal, spelled two ways
+# across the catalogue - from becoming two rows in one comparison.
+PORTAL_DISPLAY = {
+    "smartbuy": "HDFC SmartBuy", "travel_edge": "Axis Travel Edge", "ishop": "ICICI iShop",
+    "hsbc_rewards": "HSBC Rewards Marketplace", "amex_rewards": "Amex Reward Multiplier",
+    "scapia": "the Scapia app",
+}
+
+
+def _portal_key(pname: str) -> str:
+    return PORTAL_KEYS.get(pname, pname.lower().replace(" ", "_"))
 
 
 def _portal_value(card, category: str, amount: float) -> float:
@@ -253,7 +284,7 @@ def _portal_value(card, category: str, amount: float) -> float:
 
 
 def _portal_options(held_card_ids: List[str], category: str, amount: float) -> List[Dict]:
-    best: Dict[str, tuple] = {}   # portal name -> (card_id, value, card_name)
+    best: Dict[str, tuple] = {}   # portal KEY -> (card_id, value, card_name, raw portal name)
     for cid in held_card_ids:
         card = CATALOGUE_BY_ID.get(cid)
         if not card or not card.portal_name:
@@ -261,24 +292,27 @@ def _portal_options(held_card_ids: List[str], category: str, amount: float) -> L
         v = _portal_value(card, category, amount)
         if v <= 0:
             continue
-        cur = best.get(card.portal_name)
+        k = _portal_key(card.portal_name)
+        cur = best.get(k)
         if cur is None or v > cur[1]:
-            best[card.portal_name] = (cid, v, card.name)
+            best[k] = (cid, v, card.name, card.portal_name)
     opts = []
-    for pname, (cid, v, cname) in best.items():
+    for key, (cid, v, cname, raw_name) in best.items():
+        pname = PORTAL_DISPLAY.get(key, raw_name)
         opts.append({
-            "channel_key": PORTAL_KEYS.get(pname, pname.lower().replace(" ", "_")),
+            "channel_key": key,
             "channel_name": pname,
             "how": f"Book inside {pname} paying with {cname}",
             "best_card_id": cid,
             "best_card_name": cname,
             "reward_inr": v,
             "instant_offer_inr": 0.0,
+            "instant_offer_code": None,
             "total_benefit_inr": v,
             "effective_pct": _r2(v / amount * 100.0) if amount else 0.0,
             "availability": "available",
             "via_portal": True,
-            "book_url": PORTAL_URLS.get(pname),
+            "book_url": PORTAL_URLS.get(raw_name),
             # A portal quotes its own fare behind a login, so we never have one.
             "price_inr": _r2(float(amount)),
             "price_known": False,
@@ -499,6 +533,7 @@ def compare_channels(
             "best_card_name": top["card_name"],
             "reward_inr": top["reward_value_inr"],
             "instant_offer_inr": top["instant_offer_inr"],
+            "instant_offer_code": top.get("instant_offer_code"),
             "total_benefit_inr": top["total_value_inr"],
             "effective_pct": top["effective_rate_pct"],
             "availability": avail,

app/flight_sellers.py

@@ -30,7 +30,9 @@ import hashlib
 import json
 import os
 import re
+import threading
 import time
+from datetime import datetime
 from typing import Dict, List, Optional, Tuple
 
 SERPAPI_URL = "https://serpapi.com/search"
@@ -157,7 +159,42 @@ def _params(
 # own timing. Exposed via /flights/search's search_debug so a live check can
 # prove whether deep_search actually reached and ran upstream - the parameter
 # was being sent yet fast flat-priced results kept coming back.
-LAST_META: Dict = {}
+# PER-REQUEST, not process-wide. FastAPI runs these sync endpoints in a
+# threadpool, so a single module global was overwritten by every concurrent
+# call - and it carries the caller's echoed departure_id, arrival_id,
+# outbound_date and passenger counts, which meant one user's search_debug
+# could describe ANOTHER user's route. Thread-local keeps the diagnostic
+# without the leak.
+_META = threading.local()
+
+
+class _LastMetaProxy:
+    """Reads like the old module attribute (flight_sellers.LAST_META) but
+    resolves to the calling thread's own value."""
+
+    def _v(self) -> Dict:
+        return getattr(_META, "value", {}) or {}
+
+    def get(self, k, default=None):
+        return self._v().get(k, default)
+
+    def __bool__(self):
+        return bool(self._v())
+
+    def __iter__(self):
+        return iter(self._v())
+
+    def __getitem__(self, k):
+        return self._v()[k]
+
+    def __repr__(self):
+        return repr(self._v())
+
+    def to_dict(self) -> Dict:
+        return dict(self._v())
+
+
+LAST_META = _LastMetaProxy()
 
 
 def _get(params: Dict) -> Dict:
@@ -168,11 +205,10 @@ def _get(params: Dict) -> Dict:
         r = client.get(SERPAPI_URL, params=params)
         r.raise_for_status()
         data = r.json()
-        global LAST_META
         sm = data.get("search_metadata") or {}
         echo = dict(data.get("search_parameters") or {})
         echo.pop("api_key", None)   # never reflect the key
-        LAST_META = {
+        _META.value = {
             "upstream_time_s": sm.get("total_time_taken"),
             "status": sm.get("status"),
             # When this differs from now, upstream served a stored result:
@@ -222,7 +258,11 @@ def _itinerary(entry: Dict, requested_date: str) -> Optional[Dict]:
         "duration_min": entry.get("total_duration"),
         "seats_left": None,
         "found_at": None,
-        "date_offset": 0,
+        # The app ranks and tags on date_offset; hardcoding 0 while computing
+        # is_alt_date from the same comparison meant an alternate-date row
+        # sorted as if it were on the requested date and rendered without its
+        # "+1d" tag.
+        "date_offset": _day_delta(requested_date, date_part),
         "is_alt_date": date_part != requested_date,
         "oneway_fallback": False,
         "book_url": None,          # filled per-seller by sellers_for()
@@ -232,10 +272,31 @@ def _itinerary(entry: Dict, requested_date: str) -> Optional[Dict]:
         # booking token only appears once that leg is chosen. See
         # _resolve_round_trip_token.
         "departure_token": entry.get("departure_token") or "",
-        "offer_id": flight_no or (entry.get("booking_token") or entry.get("departure_token") or "")[:12],
+        # THE WHOLE ITINERARY, not just the first leg's flight number. Two
+        # genuinely different itineraries routinely open with the same flight -
+        # MAA->SXR returned "6E 2369" at 1 stop / ₹10,865 and at 2 stops /
+        # ₹11,338, both with offer_id "6E 2369". The app keys selection, dedupe
+        # and prefetched quotes on offer_id, so it handed /flights/sellers the
+        # wrong token and quoted a price for a flight the user had not chosen.
+        "offer_id": "|".join([
+            flight_no or "",
+            dep_time or "",
+            str(max(0, len(legs) - 1)),
+            (entry.get("booking_token") or entry.get("departure_token") or "")[:8],
+        ]),
     }
 
 
+def _day_delta(requested: str, actual: str) -> int:
+    """Whole days from the REQUESTED date to the date this fare actually flies."""
+    try:
+        a = datetime.strptime(requested, "%Y-%m-%d").date()
+        b = datetime.strptime(actual, "%Y-%m-%d").date()
+    except (ValueError, TypeError):
+        return 0
+    return (b - a).days
+
+
 def _matches(row: Dict, nonstop: Optional[bool], airlines: Optional[List[str]],
              max_price: Optional[float]) -> bool:
     """Same filter semantics as flights_provider, applied client-side."""
@@ -478,13 +539,37 @@ def return_options(
         legs = e.get("flights") or []
         if not legs or e.get("price") is None or not e.get("booking_token"):
             continue
-        cut = 0
-        for i, leg in enumerate(legs):
-            dep_t = ((leg.get("departure_airport") or {}).get("time") or "")
-            if return_date and dep_t[:10] >= return_date:
-                cut = i
+        # WHERE DOES THE RETURN JOURNEY START?
+        #
+        # By GEOGRAPHY, not by date. The old test took the first leg departing
+        # on or after return_date, which broke two real itineraries:
+        #   - a SAME-DAY round trip (date == return_date) matched leg 0, so
+        #     cut == 0, and `if cut else legs` then kept EVERY leg - producing
+        #     exactly the DEL->DEL, 1-stop, 260-minute "both journeys combined"
+        #     tile this code exists to prevent;
+        #   - an OVERNIGHT outbound connection pushed its second leg onto the
+        #     return date, so half the outbound was spliced onto the return and
+        #     the user was told their return departed BOM at 03:15 when it
+        #     actually departed DXB at 22:00.
+        #
+        # The return journey is the run of legs that begins where the whole
+        # itinerary began - the first leg AFTER the outbound reaches the
+        # farthest point and turns around, i.e. the first leg departing from
+        # the itinerary's original origin. `cut is None` means we could not
+        # identify it, and an unidentified boundary must SKIP the row rather
+        # than fall back to "use all legs" and quote a fabricated journey.
+        # The outbound ends the FIRST time the itinerary arrives at the
+        # destination this search asked for; everything after that is the
+        # return. Geography, not dates.
+        want_dst = {p.strip().upper() for p in (dst or "").split(",") if p.strip()}
+        cut = None
+        for i, leg in enumerate(legs[:-1]):
+            if ((leg.get("arrival_airport") or {}).get("id") or "").upper() in want_dst:
+                cut = i + 1
                 break
-        rlegs = legs[cut:] if cut else legs
+        if cut is None:
+            continue
+        rlegs = legs[cut:]
         first, last = rlegs[0], rlegs[-1]
         dep = first.get("departure_airport") or {}
         arr = last.get("arrival_airport") or {}
@@ -510,7 +595,15 @@ def return_options(
             "book_url": None,
             "booking_token": e.get("booking_token") or "",
             "departure_token": "",
-            "offer_id": (first.get("flight_number") or "") + "|" + (e.get("booking_token") or "")[:8],
+            # Same rule as the outbound rows: a return pairing that opens with
+            # the same flight number as another pairing must not collide.
+            # AI 2838 came back twice live, at ₹20,953 and ₹22,507.
+            "offer_id": "|".join([
+                first.get("flight_number") or "",
+                (first.get("departure_airport", {}) or {}).get("time", ""),
+                str(len(legs) - 1),
+                (e.get("booking_token") or "")[:8],
+            ]),
         })
     rows.sort(key=lambda r: r["fare_inr"])
     # Belt over Google's own filtering: a stop cap the upstream ignored must

app/geo.py

@@ -84,6 +84,29 @@ def iata_is_international(code: Optional[str]) -> Optional[bool]:
     return False if all_india else None
 
 
+def route_is_international(src: Optional[str], dst: Optional[str]) -> Optional[bool]:
+    """Is this ROUTE international? Judged on BOTH endpoints, not the destination.
+
+    Classifying by destination alone made every INBOUND leg domestic: DXB->BOM
+    returned False because BOM is in INDIA_IATA, so the 103 domestic-scoped
+    offers were kept on a genuinely international ticket and the 70
+    international-scoped ones were dropped. The same ₹40,000 fare therefore
+    scored differently in each direction - overstated coming home, understated
+    going out.
+
+    True if EITHER endpoint is international; False only when both are known
+    domestic; None when anything is unrecognised, which callers treat as the
+    safe domestic default. Mirrored in app/src/data/geo.ts.
+    """
+    a = iata_is_international(src)
+    b = iata_is_international(dst)
+    if a is True or b is True:
+        return True
+    if a is False and b is False:
+        return False
+    return None
+
+
 def city_is_international(name: Optional[str]) -> Optional[bool]:
     if not name:
         return None

app/main.py

@@ -457,7 +457,8 @@ def flights_search(req: FlightSearchRequest, request: Request = None):
     persona = req.persona or demo_data.DEMO_PERSONA
     city = normalize_city(req.city)
     import geo
-    intl = geo.iata_is_international(req.dst)   # international route? offers gate on it
+    # BOTH endpoints: a return leg into India is still an international trip.
+    intl = geo.route_is_international(req.src, req.dst)   # international route? offers gate on it
 
     # SerpApi's Google Flights results carry a booking token, which is what
     # unlocks per-platform prices later via /flights/sellers. Prefer it when a
@@ -491,7 +492,15 @@ def flights_search(req: FlightSearchRequest, request: Request = None):
             window_days=req.window_days if req.window_days is not None else 3,
             return_date=req.return_date,
         )
-        source = "travelpayouts" if flights_provider.is_live() else "sample (no token)"
+        # SAY WHY WE FELL BACK. Overwriting source unconditionally made a
+        # SerpAPI timeout, a rate-limit and an honest "this route has no
+        # flights" indistinguishable - all three logged as
+        # source=travelpayouts, count=0. The upstream's own status is right
+        # there in LAST_META; carry it.
+        _meta = flight_sellers.LAST_META.to_dict()
+        _why = _meta.get("status") or _meta.get("error")
+        _base = "travelpayouts" if flights_provider.is_live() else "sample (no token)"
+        source = f"{_base} (primary: {_why})" if _why and _why != "Success" else _base
         fares_live = False   # cached prices, 2-7 days old by the provider's own docs
     else:
         fares_live = bool(flights)   # a real quote pulled for this route and date
@@ -512,7 +521,16 @@ def flights_search(req: FlightSearchRequest, request: Request = None):
         results.append({"flight": f, "channel_comparison": cmp})
 
     return {
-        "query": {"src": req.src.upper(), "dst": req.dst.upper(), "date": req.date, "city": city},
+        # return_date belongs in the echo: without it neither a client nor a
+        # log could tell a ₹20,467 ROUND-TRIP PAIRING TOTAL from a ₹20,467
+        # one-way fare, and the rows themselves are shaped like one-way legs.
+        "query": {
+            "src": req.src.upper(), "dst": req.dst.upper(), "date": req.date,
+            "return_date": req.return_date, "city": city,
+        },
+        # Every fare in `results` is a pairing total when this is true.
+        "round_trip": bool(req.return_date),
+        "fare_basis": "pairing_total" if req.return_date else "one_way",
         # live = a fare quoted for this search, not merely "a token is set".
         # The cached-fare path reports false even when its token is configured.
         "live": fares_live,
@@ -520,7 +538,7 @@ def flights_search(req: FlightSearchRequest, request: Request = None):
         "per_platform_prices": flight_sellers.is_live(),   # can /flights/sellers answer?
         # Upstream's own account of the last call (its parameter echo and
         # timing) - live proof of whether deep_search ran, key never included.
-        "search_debug": getattr(flight_sellers, "LAST_META", None),
+        "search_debug": flight_sellers.LAST_META.to_dict(),
         "count": len(results),
         "results": results,
     }
@@ -564,7 +582,7 @@ def flights_sellers(req: FlightSellersRequest, request: Request = None):
             brand_key=None, merchant=None, rail="card",
             persona=req.persona or demo_data.DEMO_PERSONA,
             city=normalize_city(req.city),
-            international=geo.iata_is_international(req.dst),
+            international=geo.route_is_international(req.src, req.dst),
             passengers=(req.adults or 1) + (req.children or 0),
             round_trip=bool(getattr(req, "return_date", None)),
             channel_prices=data["channel_prices"],

app/offers.py

@@ -19,10 +19,26 @@ Each offer is structured (not free text), so the engine can value it exactly:
 
 import re
 from dataclasses import dataclass, field, asdict
-from datetime import date
+from datetime import date, datetime, timedelta, timezone
 from typing import Dict, List, Optional
 
 
+
+# THE SERVER'S "TODAY" IS INDIA'S TODAY.
+#
+# date.today() on a UTC host is still YESTERDAY between 00:00 and 05:30 IST.
+# The app deliberately uses a LOCAL date (offers.ts: toLocaleDateString('en-CA'),
+# with a comment explaining exactly this), but the server is the only source of
+# offers - anything not active on the UTC date is never sent, and the app cannot
+# re-add what it never received. Measured: 80 offers unreachable at 02:00 IST on
+# a Monday, including every Monday-gated row.
+_IST = timezone(timedelta(hours=5, minutes=30))
+
+
+def _today_ist() -> str:
+    return datetime.now(_IST).date().isoformat()
+
+
 def _inr(n: float) -> str:
     """Indian digit grouping: 1,00,000 - not 100,000.
 
@@ -515,14 +531,21 @@ _TRAVEL_OTAS = {"makemytrip", "goibibo", "easemytrip", "cleartrip", "yatra", "ix
 _CAT_WORDS = [
     (re.compile(r"\b(flights?|airfares?)\b", re.I), "travel_flights"),
     (re.compile(r"\bhotels?\b", re.I), "travel_hotels"),
-    (re.compile(r"\b(bus|buses)\b", re.I), "bus"),
-    (re.compile(r"\b(cabs?|car rentals?)\b", re.I), "cabs"),
+    # "bus"/"cabs"/"holiday" are NOT categories the engine knows - the Category
+    # union and MERCHANT_MAP never produce them - so scoping an offer to one
+    # made offer_value's category gate return 0 forever. A verified AU Bank
+    # "10% off, up to ₹200" on AbhiBus paid out nothing, and a zeroed offer
+    # looks identical to no offer, so it was invisible. Map onto the vocabulary
+    # the scorer actually speaks.
+    (re.compile(r"\b(bus|buses)\b", re.I), "transport"),
+    (re.compile(r"\b(cabs?|car rentals?)\b", re.I), "transport"),
 ]
 # Only meaningful for a travel OTA: "package" and "holiday" are ordinary words
 # elsewhere (a spa package, a holiday menu) and would scope a dining offer out
 # of dining.
 _OTA_ONLY_CAT_WORDS = [
-    (re.compile(r"\b(holidays?|packages?)\b", re.I), "holiday"),
+    # A holiday package is a hotel + a flight; both are priceable categories.
+    (re.compile(r"\b(holidays?|packages?)\b", re.I), "travel_hotels"),
 ]
 
 
@@ -667,11 +690,55 @@ def _best_unlinked(offs, amount, category, channel, conditional: bool):
     return best, note, code, prebook
 
 
+def scope_filter(offers, scope) -> list:
+    """TRIP SCOPE: geo, party size and one-way vs round trip.
+
+    These gates lived ONLY inside compare_channels, so the channel rows honoured
+    them and the card recommendation did not - the same response carried
+    "instant offer 3000" on the card and 799 on the channel row, because the
+    card had been given Yatra's THREE-PASSENGER ROUND-TRIP slab for a
+    one-passenger one-way fare. Same shape for geo: an international-only hotel
+    offer paid out on a domestic stay. Living here, where every consumer reaches
+    it, is what stops a caller forgetting it. Mirror of offers.ts scopeFilter.
+
+    Unknown scope means DO NOT FILTER: a null passenger count must not silently
+    delete every slabbed offer from a non-travel scoring.
+    """
+    if not scope:
+        return list(offers or [])
+    intl = bool(scope.get("international"))
+    known_pax = scope.get("passengers") is not None
+    pax = scope.get("passengers") or 1
+    known_trip = scope.get("round_trip") is not None
+    rt = bool(scope.get("round_trip"))
+    out = []
+    for o in offers or []:
+        g = o.get("geo") or "any"
+        if g == "international" and not intl:
+            continue
+        if g == "domestic" and intl:
+            continue
+        if known_pax and int(o.get("min_passengers") or 0) > pax:
+            continue
+        if known_trip:
+            tt = str(o.get("trip_type") or "any").lower()
+            if tt == "round" and not rt:
+                continue
+            if tt == "oneway" and rt:
+                continue
+        out.append(o)
+    return out
+
+
 def offer_value(off: Dict, amount: float, category: Optional[str] = None) -> float:
     """Monetary value of a (dict) offer for a given spend. 0 if not applicable."""
     if amount < (off.get("min_spend") or 0):
         return 0.0
-    cats = off.get("categories")
+    # `[]` is FALSY in Python and TRUTHY in JS, so an offer carrying an empty
+    # categories array paid out in full server-side and scored zero on device.
+    # No curated row has one today; one ingestion row would silently split the
+    # two rails. Both now treat "no categories" as "not scoped".
+    cats = off.get("categories") or None
     if cats and category is not None and category not in cats:
         return 0.0
     t = off.get("type")
@@ -719,7 +786,7 @@ def _days_between(a: str, b: str) -> int:
 
 def is_fresh(off: Offer, today: Optional[str] = None) -> bool:
     """Was this offer verified recently enough to still be worth asserting?"""
-    today = today or date.today().isoformat()
+    today = today or _today_ist()
     return _days_between(off.last_verified, today) <= MAX_VERIFIED_AGE_DAYS
 
 
@@ -741,7 +808,7 @@ def has_provenance(off: Offer) -> bool:
 
 
 def _active(off: Offer, today: Optional[str]) -> bool:
-    today = today or date.today().isoformat()
+    today = today or _today_ist()
     if not (off.valid_from <= today <= off.valid_to):
         return False
     # Day-of-week scope: an offer the page limits to certain weekdays does not

app/scoring_engine.py

@@ -20,7 +20,7 @@ Design principles:
      on a single transaction.
 """
 
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from typing import Dict, List, Optional
 
 from card_catalogue import Card, CATALOGUE_BY_ID, all_cards
@@ -64,6 +64,12 @@ class TxnContext:
     offers: Optional[List[Dict]] = None
     rail: str = "card"               # "card" (POS/online) or "upi" (RuPay credit-on-UPI)
     channel: Optional[str] = None    # "online" | "offline"; when known, filters offers by channel
+    # TRIP SCOPE for travel scorings. None means "unknown, do not filter on it".
+    # Enforced in score_transaction via offers.scope_filter, so the card
+    # recommendation can no longer price a slab the channel rows refuse.
+    international: Optional[bool] = None
+    passengers: Optional[int] = None
+    round_trip: Optional[bool] = None
 
 
 @dataclass
@@ -87,6 +93,9 @@ class CardScore:
     emi_offer_inr: float = 0.0
     emi_offer_text: Optional[str] = None
     emi_offer_code: Optional[str] = None
+    # The promo code the PRICED instant discount needs, when it needs one.
+    # Mirror of CardScore.instantOfferCode in engine.ts.
+    instant_offer_code: Optional[str] = None
 
 
 def _offer_applies(off: Dict, card: Card, allow_emi: bool = False) -> bool:
@@ -127,7 +136,12 @@ def _offer_applies(off: Dict, card: Card, allow_emi: bool = False) -> bool:
     # Issuer-level offers still carry hidden card scoping the issuer field ignores:
     # a network limit ("Mastercard only") or a debit-card requirement. Enforce both,
     # else an HDFC-Mastercard-debit offer wrongly credits an HDFC-RuPay-credit card.
-    if off.get("requires_debit"):      # catalogue is credit cards -> never applies
+    # CARD KIND. The old comment claimed the catalogue is credit cards; that has
+    # been false since the debit cards were added - there are 19. With no
+    # inverse gate, an issuer-wide offer whose own evidence reads "ICICI Bank
+    # CREDIT Card 25% discount" paid out on that issuer's DEBIT card, and could
+    # make the debit card win the comparison outright. Both directions now hold.
+    if bool(off.get("requires_debit")) != (getattr(card, "kind", "credit") == "debit"):
         return False
     net = (off.get("network") or "any").lower()
     if net != "any" and net != (card.network or "").lower():
@@ -140,6 +154,11 @@ def _instant_offer_value(card: Card, ctx: TxnContext):
     from offers import offer_value
     best = 0.0
     note = None
+    # THE CODE COMES OUT TOO. _offer_applies prices a card-linked offer as soon
+    # as its promo_code is non-empty, but this returned only the money - so 50
+    # active offers were priced into the headline with the code the user has to
+    # type never surfaced anywhere. Mirror of engine.ts instantOffer.
+    code = None
     for off in (ctx.offers or []):
         if not _offer_applies(off, card):
             continue
@@ -160,7 +179,8 @@ def _instant_offer_value(card: Card, ctx: TxnContext):
             val = ctx.amount * float(pct.group(1)) / 100.0 if pct else (float(flat.group(1).replace(",", "")) if flat else 0.0)
         if val > best:
             best, note = val, txt
-    return best, note
+            code = (off.get("promo_code") or "").strip() or None
+    return best, note, code
 
 
 def _emi_offer_value(card: Card, ctx: TxnContext):
@@ -188,6 +208,15 @@ def _emi_offer_value(card: Card, ctx: TxnContext):
     return best, note, code
 
 
+def _closed_or_debit(card_id: str) -> bool:
+    """Cards that must never be offered as a DISCOVERY ("you should apply for
+    this"). Mirror of engine.ts, which excludes both."""
+    c = CATALOGUE_BY_ID.get(card_id)
+    if c is None:
+        return False
+    return bool(getattr(c, "closed", False)) or getattr(c, "kind", "credit") == "debit"
+
+
 def score_transaction(
     held_card_ids: List[str],
     ctx: TxnContext,
@@ -204,6 +233,16 @@ def score_transaction(
     mtd_spend: {card_id: {category: rupees_spent_this_month}}
     """
     mtd_spend = mtd_spend or {}
+    # Trip scope applied ONCE, here, so every downstream consumer of ctx.offers
+    # inherits it. compare_channels also pre-filters; the predicate is
+    # idempotent, so neither can be the only guard.
+    if ctx.offers:
+        from offers import scope_filter
+        ctx = replace(ctx, offers=scope_filter(ctx.offers, {
+            "international": ctx.international,
+            "passengers": ctx.passengers,
+            "round_trip": ctx.round_trip,
+        }))
     persona = persona or []
     held_scores: List[CardScore] = []
     all_scores: List[CardScore] = []
@@ -278,10 +317,10 @@ def score_transaction(
 
         # --- instant offers (don't apply on the UPI rail) ---
         if rail == "upi":
-            offer_inr, offer_note = 0.0, None
+            offer_inr, offer_note, offer_code = 0.0, None, None
             emi_inr, emi_note, emi_code = 0.0, None, None
         else:
-            offer_inr, offer_note = _instant_offer_value(card, ctx)
+            offer_inr, offer_note, offer_code = _instant_offer_value(card, ctx)
             emi_inr, emi_note, emi_code = _emi_offer_value(card, ctx)
 
         total = reward_inr + offer_inr
@@ -335,6 +374,7 @@ def score_transaction(
             network=card.network,
             reward_value_inr=_r2(reward_inr),
             instant_offer_inr=_r2(offer_inr),
+            instant_offer_code=offer_code,
             total_value_inr=_r2(total),
             raw_total=total,
             effective_rate_pct=_r2(eff_pct),
@@ -356,7 +396,11 @@ def score_transaction(
     _upi_ok = {c.id for c in all_cards() if getattr(c, "upi_eligible", False)}
     def _rank_key(s):
         demerit = 1 if (rail == "upi" and s.card_id not in _upi_ok) else 0
-        return (demerit, -s.raw_total)
+        # Card id is the FINAL tie-break. Without it a tie was broken by
+        # catalogue insertion order, and card_catalogue.py and cards.ts list the
+        # same 139 ids in different order - so the server and the app named
+        # DIFFERENT winners for the same tied purchase. Mirror of engine.ts.
+        return (demerit, -s.raw_total, s.card_id)
     held_scores.sort(key=_rank_key)
     all_scores.sort(key=_rank_key)
 
@@ -400,11 +444,17 @@ def score_transaction(
     if include_discovery and held_scores:
         best_held = held_scores[0].total_value_inr
         for sc in all_scores:
+            # "Apply for this card" must never name a card no one can apply for,
+            # nor a DEBIT card (you do not choose a debit card for its rewards).
+            # engine.ts filtered both; this rail filtered neither, so the server
+            # recommended Axis Atlas - closed to new applicants since Sep 2025.
+            if _closed_or_debit(sc.card_id):
+                continue
             if not sc.held and sc.total_value_inr > best_held * 1.10:  # >10% better
                 discovery = sc
                 break
     elif include_discovery and not held_scores:
-        discovery = next((s for s in all_scores if not s.held), None)
+        discovery = next((s for s in all_scores if not s.held and not _closed_or_debit(s.card_id)), None)
 
     # --- richer reasoning for the better card the user does NOT hold ---
     if discovery:

app/statement_parser.py

@@ -30,15 +30,23 @@ _AMOUNT_LENIENT_RE = re.compile(r"(-?\d[\d,]*(?:\.\d{1,2})?)")  # integer-or-dec
 
 
 def _parse_amount_cell(s: str):
-    """Parse a value from a known amount column: tolerate Rs/INR/₹, '/-', and missing decimals."""
+    """Parse a value from a known amount column: tolerate Rs/INR/₹, '/-', and missing decimals.
+
+    "(1,200.00)" is the accounting convention for a CREDIT. The regex matched
+    happily inside the brackets and returned +1200, so a refund imported as a
+    purchase. _normalise_amount_signs exists for exactly this and was only ever
+    wired into the PDF path, never the CSV one.
+    """
     cleaned = re.sub(r"(?:rs\.?|inr|₹)", "", s or "", flags=re.IGNORECASE).replace("/-", "").strip()
+    negated = bool(re.fullmatch(r"\(\s*[^)]*\)", cleaned))
     m = _AMOUNT_LENIENT_RE.search(cleaned)
     if not m:
         return None
     try:
-        return float(m.group(1).replace(",", ""))
+        v = float(m.group(1).replace(",", ""))
     except ValueError:
         return None
+    return -abs(v) if negated else v
 _DATE_TOKEN_RE = re.compile(
     r"(\d{1,2}[/\-.]\d{1,2}[/\-.]\d{2,4}|\d{1,2}[ \-]\w{3}[ \-]\d{2,4}|\d{4}-\d{2}-\d{2})"
 )
@@ -277,6 +285,15 @@ def parse_csv(content: bytes, reversals: Optional[List[Dict]] = None) -> List[Di
             if not amount:
                 continue
             desc = r[ci] if 0 <= ci < len(r) else " ".join(r)
+            # Signed single-amount statements: a NEGATIVE row is a CREDIT.
+            # _normalize_row does abs(), so without this branch a -899.00 refund
+            # imported as a +899.00 purchase - a 2x error on that row plus
+            # phantom rewards. The TS parser has always had this; the Python
+            # CSV path never did.
+            if amount < 0:
+                if _credit_kind("cr", desc) == "refund" and reversals is not None:
+                    reversals.append({"date": iso, "description": desc.strip(), "amount": round(abs(amount), 2)})
+                continue
             direction = r[ki] if 0 <= ki < len(r) else ""
             kind = _credit_kind(direction, desc)
             if kind == "refund":
@@ -462,11 +479,71 @@ def _statement_period(blob: str):
     return (a, b) if a and b and a <= b else None
 
 
+def _has_balance_column(lines: List[str]) -> bool:
+    """Does this statement print a RUNNING BALANCE after the amount?
+
+    Decided across the whole file rather than row by row, by the only property
+    that actually identifies a balance column: successive balances differ by
+    that row's amount. Kotak and several PSU layouts do this; most issuers do
+    not, and mis-classifying either way corrupts every figure in the import, so
+    the bar is deliberately high - at least two CONSECUTIVE confirmed pairs and
+    at least 70% of all pairs consistent. Two independent arithmetic
+    coincidences are needed for a false positive; a forex sub-amount column
+    ("USD 25.00  1,200.00") fails immediately because the left figure bears no
+    relation to the difference between the right ones.
+
+    Direction is not assumed: a card statement's balance rises with spend, a
+    bank account's falls, so |balance_n - balance_(n-1)| == amount_n is the
+    test.
+    """
+    rows: List[tuple] = []
+    for raw in lines:
+        line = (raw or "").strip()
+        if not line or _SUMMARY_RE.search(line.lower()):
+            continue
+        line = _normalise_amount_signs(line)
+        dm = _PDF_DATE_RE.search(line)
+        md = None if dm else _MONTH_DAY_RE.search(line)
+        if not (dm or md):
+            continue
+        amts = list(_SIGNED_AMT_RE.finditer(line))
+        if len(amts) < 2:
+            rows.append(())          # a 1-figure row breaks the balance chain
+            continue
+        try:
+            last = float(amts[-1].group(1).replace(",", ""))
+            prev = float(amts[-2].group(1).replace(",", ""))
+        except ValueError:
+            rows.append(())
+            continue
+        rows.append((prev, last))
+
+    ok = bad = 0
+    for i in range(1, len(rows)):
+        a, b = rows[i - 1], rows[i]
+        if len(a) != 2 or len(b) != 2:
+            continue
+        amount, balance = b
+        if abs(abs(balance - a[1]) - abs(amount)) < 0.51:
+            ok += 1
+        else:
+            bad += 1
+    return ok >= 2 and ok >= (ok + bad) * 0.7
+
+
 def _parse_pdf_lines(lines: List[str], gated: bool = True, reversals: Optional[List[Dict]] = None) -> List[Dict]:
     out: List[Dict] = []
     started = not gated          # ungated fallback: parse from the top
     pending: List[str] = []      # buffered wrapped merchant-name lines (IDFC style)
-    _running = 0.0               # running total, to recognise a balance column
+    # Decided ONCE for the whole statement by _has_balance_column below, not
+    # inferred row by row. The old streaming test asked whether
+    # (_running + prev) == last, but _running was only ever assigned INSIDE that
+    # same branch and started at 0.0 - so it could only bootstrap on a statement
+    # whose opening balance was zero. Credit-card statements always carry a
+    # previous balance, so the branch never fired and EVERY row on a
+    # balance-column layout imported the running balance as the spend, with the
+    # error compounding down the page.
+    _balance_col = _has_balance_column(lines)
     # Year for month-first dates that omit it (Amex "June 03").
     #
     # This used to take max() of every 4-digit year printed anywhere, so a
@@ -517,29 +594,10 @@ def _parse_pdf_lines(lines: List[str], gated: bool = True, reversals: Optional[L
                 if re.search(r"[A-Za-z]", line):
                     pending = (pending + [line])[-2:]
                 continue
-            # RUNNING-BALANCE COLUMN. Taking the last money figure imports the
-            # BALANCE as the spend on layouts that print one after the amount
-            # (Kotak and several PSU formats): every row is wrong and the error
-            # compounds down the statement. When two figures trail the
-            # description and the last one is the running total of the previous
-            # rows plus this one, the amount is the second-to-last.
-            amt_m = amts[-1]                 # last money figure on the line is the INR amount
-            if len(amts) >= 2:
-                try:
-                    last = float(amts[-1].group(1).replace(",", ""))
-                    prev = float(amts[-2].group(1).replace(",", ""))
-                except ValueError:
-                    last = prev = None
-                if last is not None and prev is not None:
-                    if abs((_running + prev) - last) < 0.51 and prev > 0:
-                        amt_m = amts[-2]     # confirmed balance column
-                        _running = last
-                    elif _running == 0.0 and last > prev > 0 and abs(last - prev) > 0.005:
-                        # first data row of a balance layout: balance == amount, or
-                        # opening balance + amount. Only adopt when a later row confirms.
-                        pass
-            if len(amts) < 2:
-                _running = 0.0
+            # On a confirmed balance layout the amount is the SECOND-to-last
+            # figure; the last one is the running total. Decided for the file,
+            # so the first data row is classified correctly too.
+            amt_m = amts[-2] if (_balance_col and len(amts) >= 2) else amts[-1]
             amount = float(amt_m.group(1).replace(",", ""))
             tail = line[amt_m.end():].strip().upper()
             # Axis-style layouts carry the direction as its own COLUMN before
@@ -549,8 +607,15 @@ def _parse_pdf_lines(lines: List[str], gated: bool = True, reversals: Optional[L
             # reads as part of a merchant name.
             _pre_words = line[:amt_m.start()].strip().split()
             _dir_word = (_pre_words[-1].strip('.').lower() if _pre_words else "")
-            _col_credit = _dir_word in ("credit", "cr")
-            _col_debit = _dir_word in ("debit", "dr")
+            # A bare trailing "C"/"D" is HDFC's direction column. The code
+            # already knew it existed - it scrubs it out of the merchant name a
+            # few lines below - but is_credit only looked for a sign, a "CR"
+            # prefix or a Debit/Credit WORD, so a single letter was invisible
+            # and a merchant credit whose wording lacked "refund" imported as
+            # spend. The Axis long-word form was handled; this one was not.
+            _tail_letter = tail.split()[0] if tail.split() else ""
+            _col_credit = _dir_word in ("credit", "cr") or _tail_letter in ("C", "CR")
+            _col_debit = _dir_word in ("debit", "dr") or _tail_letter in ("D", "DR")
             is_credit = amount < 0 or tail.startswith("CR") or _col_credit or (not _col_debit and _is_credit("", line))
             amount = abs(amount)
             if amount == 0:                  # FX-only / zero rows