Sync from GitHub main 955be71: dual-pass merge fix + Costco receipt support

fix(ocr): the dual-pass merge ranked candidates by confidence and treated any
horizontal overlap as a duplicate, so a short high-confidence fragment was
selected before the complete line and then suppressed it — "1 Guylian
Seashells Boxed Chocolates" came out as "Chocolates". A candidate is now a
duplicate only when a selected block covers most of its width. Every price was
already correct, so this only ever showed up in the description text.

feat(parser): Costco prints the product name on the line above its item code
and price, which shifted every description onto the wrong item; and its
"TOTAL(INCL VAT)" is under a redaction bar, so "AMOUNT:" is now accepted as a
total, anchored on the colon so "VAT Amount" cannot match.

Measured on the 15-receipt corpus added in the GitHub repo (eval/, not synced
here — the Dockerfile only copies main.py, ocr/ and utils/):

description word recall 64.7% -> 90.0%
line-item price accuracy 89.4% -> 97.2%
totals 13/15 -> 15/15
correct item counts 12/15 -> 15/15

ocr/parser.py

@@ -63,7 +63,7 @@ _PRICE_EXTRACT_RE = re.compile(r"(-?)\s*[^\d\s]{0,2}\s*(\d{1,6}[.,\s]\d{2})")
 
 _TOTALS_KEYWORDS = re.compile(
     r"\b(total|sub[\s-]?total|subtotal|savings|promotions|tax|gst|hst|balance"
-    r"|amount\s+due|amount\s+payable|to\s+pay)\b",
+    r"|amount\s+due|amount\s+payable|to\s+pay)\b|\bamount\s*:",
     re.IGNORECASE,
 )
 
@@ -104,6 +104,11 @@ _TRAILING_CODE_RE = re.compile(r"\s+\d{6,}$")
 _QTY_HEADER_RE = re.compile(r"^\s*qty\b", re.IGNORECASE)
 _QTY_PREFIX_RE = re.compile(r"^([1-9]\d?)\s+(\S.{2,})$")
 
+# Bare product code opening a priced row — the Costco "description above the
+# price row" signature (see _is_desc_above_layout). Three digits minimum so a
+# leading quantity can never match.
+_ITEM_CODE_RE = re.compile(r"^\d{3,}$")
+
 # Per-unit price denominator: £0.90/kg, £1.50/litre — weight annotation, not an item price
 _PER_UNIT_PRICE_RE = re.compile(r"[£$€¥]\s*\d+[.,]\d+\s*/")
 
@@ -119,8 +124,12 @@ _PAYMENT_SKIP = re.compile(
 # spelling variants _TOTALS_KEYWORDS accepts for section detection.
 _SUBTOTAL_RE = re.compile(r"\bsub[\s-]?total\b", re.IGNORECASE)
 _SAVINGS_RE = re.compile(r"\b(saving|promotion)", re.IGNORECASE)
+# "AMOUNT: £112.55" is the only readable total on a Costco receipt, whose
+# "TOTAL(INCL VAT)" is overprinted with a redaction bar. Anchored on the colon
+# so the "VAT Amount" line further down cannot match.
 _TOTAL_RE = re.compile(
-    r"\b(total|amount\s+due|amount\s+payable|to\s+pay|balance\s+due)\b",
+    r"\b(total|amount\s+due|amount\s+payable|to\s+pay|balance\s+due)\b"
+    r"|\bamount\s*:",
     re.IGNORECASE,
 )
 
@@ -841,6 +850,8 @@ def _extract_line_items(
     """
     items: list[dict[str, Any]] = []
     current: dict[str, Any] | None = None
+    desc_above = _is_desc_above_layout(item_rows, receipt_width)
+    pending_desc: list[dict] = []
 
     for row in item_rows:
         price_blk = next(
@@ -850,7 +861,10 @@ def _extract_line_items(
         desc_blocks = [b for b in row if b is not price_blk]
 
         if price_blk is None:
-            if current is not None:
+            if desc_above:
+                # The product name precedes the row carrying its price.
+                pending_desc = desc_blocks
+            elif current is not None:
                 _append_desc(current, desc_blocks, receipt_width)
             continue
 
@@ -879,12 +893,52 @@ def _extract_line_items(
             "total_price": price_str,
             "discount": None,
         }
-        _append_desc(current, desc_blocks, receipt_width)
+        if desc_above and pending_desc:
+            # This row holds the item code, "1x" and the unit price, not the
+            # product name — that came on the row before.
+            _append_desc(current, pending_desc, receipt_width)
+            pending_desc = []
+        else:
+            # No name row was banked. On a skewed scan the name and price rows
+            # can merge into one, so this row still carries the description.
+            _append_desc(current, desc_blocks, receipt_width)
         items.append(current)
 
     return items
 
 
+def _is_desc_above_layout(item_rows: list[list[dict]], receipt_width: float) -> bool:
+    """
+    Detect the Costco-style layout where the product name sits on its own line
+    *above* the row carrying its item code, quantity and price:
+
+        KS STRAWB C/CAKE
+        7963        1x    14.99    14.99 Z
+
+    Signature: the priced row begins with a bare item code. Three or more
+    digits, so a leading quantity ("1 Pringles...", "2 Tesco...") on the
+    ordinary description-and-price-on-one-line layout can't trigger it.
+    """
+    priced = coded = 0
+    for row in item_rows:
+        price_blk = next(
+            (b for b in reversed(row) if _is_price_block(b, receipt_width)),
+            None,
+        )
+        if price_blk is None:
+            continue
+        priced += 1
+        desc_blocks = [b for b in row if b is not price_blk]
+        if not desc_blocks:
+            continue
+        leftmost = min(desc_blocks, key=lambda b: _left_x(b["bbox"]))
+        tokens = leftmost["text"].split()
+        if tokens and _ITEM_CODE_RE.match(tokens[0]):
+            coded += 1
+
+    return priced >= 3 and coded / priced >= 0.6
+
+
 def _is_desc_block(block: dict, receipt_width: float) -> bool:
     """
     Description blocks start before the price column (70% mark).

ocr/reader.py

@@ -14,6 +14,12 @@ logger = logging.getLogger(__name__)
 # Tolerance for merging overlapping blocks from dual-pass OCR (pixels)
 _MERGE_Y_TOL = 15
 _MERGE_X_TOL = 40
+# A candidate block is a duplicate only when a selected block covers at least
+# this fraction of its width. Below it the two are complementary fragments of
+# one line and both are kept, for the parser to join. On the eval corpus
+# description recall climbs to 0.7 and is flat to 0.9 (88.7% at 0.5, 90.0% at
+# 0.8) with price accuracy unchanged; below 0.3 items start being lost.
+_MERGE_COVER_RATIO = 0.8
 
 
 class PaddleOCRReader:
@@ -170,19 +176,31 @@ def _merge_blocks(primary: list[dict], secondary: list[dict]) -> list[dict]:
 
 
 def _blocks_overlap(a: dict, b: dict) -> bool:
-    """Check if two blocks overlap: y-proximity AND horizontal bbox overlap."""
+    """
+    True when candidate `a` duplicates already-selected `b`: y-proximity AND
+    `b` covering most of `a`'s width.
+
+    Treating *any* horizontal overlap as duplication discards text. The two
+    passes routinely split one line differently — pass 1 gives
+    "Guylian Seashells Boxed C" + "Chocolates", pass 2 gives the whole line —
+    and those fragments only clip each other at the edges. Dropping on a
+    one-pixel touch loses whole words; requiring real coverage keeps
+    complementary fragments so the parser can join them into one description.
+    """
     ay = _top_y(a["bbox"])
     by = _top_y(b["bbox"])
     if abs(ay - by) > _MERGE_Y_TOL:
         return False
 
-    # Check horizontal overlap of bounding boxes
     ax1 = min(pt[0] for pt in a["bbox"])
     ax2 = max(pt[0] for pt in a["bbox"])
     bx1 = min(pt[0] for pt in b["bbox"])
     bx2 = max(pt[0] for pt in b["bbox"])
 
-    return ax1 < bx2 and ax2 > bx1
+    overlap = min(ax2, bx2) - max(ax1, bx1)
+    if overlap <= 0:
+        return False
+    return overlap / max(ax2 - ax1, 1) >= _MERGE_COVER_RATIO
 
 
 def _top_y(bbox: list) -> float: