feat(wb-alerts): Phase 3b — noise-robust checkpoint name recovery

3a's live capture revealed most of the verified 67% "coverage gap" is real
WHITELISTED checkpoints lost to social-media noise, not unknown ones. find_checkpoint
gains two ADDITIVE recovery steps — they fire ONLY when exact/alias/substring all
miss, and resolve ONLY to an exact whitelist name (no open-ended fuzzy, no
wrong-checkpoint risk), so existing matches are unchanged:
  - de-elongation: collapse stretched letters (المربععه→المربعه, بحححرررري→بحري)
  - distinctive whole-token match: a known >=4-char single-token name present as a
    complete token in the de-elongated text (عطارة البرج فتحت الان → عطاره),
    recovering a real checkpoint buried in status/prefix noise. The >=4 + whole-token
    gate avoids short-substring false positives.

Validated on the REAL captured candidates against the production 234-entry KB: 3/3
real checkpoints (Atara, Al-Murabba'a, Turmus Ayya) recovered, 3/3 garbage fragments
still rejected. The status-required parser gate further guards against bare mentions.
Suite 169 passed, FP audit 96/96.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 2 people

services/westbank-alerts/app/checkpoint_knowledge_base.py

@@ -10,10 +10,17 @@
 
 import json
 import logging
+import re
 from pathlib import Path
 from typing import Optional
 from .checkpoint_parser import _normalise
 
+
+def _collapse_elongation(s: str) -> str:
+    """Collapse runs of 2+ identical characters to one — social-media letter
+    stretching (المربععه → المربعه, بحححرررري → بحري)."""
+    return re.sub(r"(.)\1+", r"\1", s)
+
 log = logging.getLogger("checkpoint_knowledge_base")
 
 
@@ -159,6 +166,35 @@ def find_checkpoint(self, name_ar: str) -> Optional[str]:
                 # Incoming is substring of known — always accept
                 return canonical_key
 
+        # ── Phase 3b: noise-robust recovery. ADDITIVE — only reached when exact /
+        # alias / substring all missed, and resolves ONLY to an exact whitelist
+        # name (no open-ended fuzzy), so existing matches are unchanged and there
+        # is no wrong-checkpoint risk.
+
+        # 3.5 De-elongation retry: collapse stretched letters and re-match
+        # (المربععه بحري → المربعه ...).
+        deelong = _collapse_elongation(name_norm)
+        if deelong != name_norm:
+            if deelong in self.by_name_norm:
+                return self.by_name_norm[deelong]
+            if deelong in self.aliases:
+                return self.aliases[deelong]
+            for norm_known, canonical_key in self.all_names:
+                if len(norm_known) >= 3 and norm_known in deelong:
+                    extra = len(deelong.split()) - len(norm_known.split())
+                    if extra <= len(norm_known.split()):
+                        return canonical_key
+
+        # 4. Distinctive whole-token match: a known single-token name of >= 4 chars
+        # appearing as a complete token in the (de-elongated) text recovers a real
+        # whitelisted checkpoint surrounded by status/prefix noise
+        # (عطارة البرج فتحت الان → عطاره). The >= 4 chars + whole-token gate avoids
+        # short-substring false positives ("تل" inside "مقاتلو").
+        tokens = set(deelong.split())
+        for norm_known, canonical_key in self.all_names:
+            if len(norm_known) >= 4 and " " not in norm_known and norm_known in tokens:
+                return canonical_key
+
         return None
 
     def get_checkpoint(self, canonical_key: str) -> Optional[dict]:

services/westbank-alerts/test_checkpoint_recovery.py

@@ -0,0 +1,70 @@
+"""Phase 3b: recover real WHITELISTED checkpoints buried in social-media noise.
+
+The live candidate capture (3a) revealed that much of the 67% "coverage gap" is
+not unknown checkpoints — it's known ones the strict matcher dropped because the
+name carried noise: letter elongation (المربععه), trailing status words
+(عطارة البرج فتحت الان), entrance prefixes (على مدخل ترمسعيا).
+
+These are purely-additive recovery steps in find_checkpoint: they fire ONLY when
+exact/alias/substring all miss, and only resolve to an EXACT whitelist name (no
+open-ended fuzzy), so existing matches are unchanged and there is no
+wrong-checkpoint risk. Garbage and too-short tokens must still miss.
+"""
+import os
+os.environ.setdefault("API_SECRET_KEY", "test-secret-key-0123456789abcdef")
+
+from app.checkpoint_knowledge_base import CheckpointKnowledgeBase
+from app.checkpoint_parser import _normalise
+
+
+def _kb():
+    kb = CheckpointKnowledgeBase()
+    rows = [
+        ("عطاره", "عطارة", "Atara"),
+        ("المربعه", "المربعة", "Al-Murabbaa"),
+        ("ترمسعيا", "ترمسعيا", "Turmus Ayya"),
+        ("بيتا", "بيتا", "Beita"),  # 4-char name, for the distinctive-token guard
+    ]
+    for ck, name_ar, name_en in rows:
+        cp = {"canonical_key": ck, "name_ar": name_ar, "name_en": name_en,
+              "region": "x", "checkpoint_type": "checkpoint", "latitude": 32.0, "longitude": 35.0}
+        kb.by_canonical_key[ck] = cp
+        n = _normalise(name_ar)
+        kb.by_name_norm[n] = ck
+        kb.all_names.append((n, ck))
+    kb.all_names.sort(key=lambda x: -len(x[0]))
+    return kb
+
+
+def test_clean_names_still_match_exactly():
+    kb = _kb()
+    assert kb.find_checkpoint("عطارة") == "عطاره"
+    assert kb.find_checkpoint("ترمسعيا") == "ترمسعيا"
+
+
+def test_recovers_letter_elongation():
+    # المربععه (doubled ع) + garbled suffix → Al-Murabba'a.
+    assert _kb().find_checkpoint("المربععه بحححرررري") == "المربعه"
+
+
+def test_recovers_trailing_status_words():
+    # عطارة + "البرج فتحت الان" (the tower opened now) → Atara.
+    assert _kb().find_checkpoint("عطارة البرج فتحت الان") == "عطاره"
+
+
+def test_recovers_entrance_prefix():
+    # "على مدخل" (at the entrance of) + ترمسعيا → Turmus Ayya.
+    assert _kb().find_checkpoint("على مدخل ترمسعيا") == "ترمسعيا"
+
+
+def test_garbage_fragments_still_miss():
+    kb = _kb()
+    for junk in ["صار في", "وفي", "اندماج", "الوضع هادئ"]:
+        assert kb.find_checkpoint(junk) is None, junk
+
+
+def test_short_token_not_distinctive_enough():
+    # A <4-char token must not match as a distinctive whole-token (avoids the
+    # "تل inside مقاتلو" class of false positive). "في" is 2 chars.
+    kb = _kb()
+    assert kb.find_checkpoint("شيء ما في مكان") is None