Upload folder using huggingface_hub

app/validator/engine.py

@@ -75,9 +75,11 @@ def _build_reason_code(
 ) -> str | None:
     """Machine cause for the verdict. Ordered most-specific/actionable first.
 
-    disposable outranks everything (frontend classifies it as Disposable);
-    a catch-all or a dead-A-only route outranks a raw SMTP code so the reason
-    matches the Unknown verdict the frontend assigns for those rows.
+    disposable outranks everything (frontend classifies it as Disposable). A
+    definitive SMTP rejection (verified False + code) outranks the domain-level
+    catch-all flag: reporting "catch_all_detected" beside status=invalid is
+    incoherent — the explicit "mailbox does not exist" is the actionable fact.
+    Catch-all then outranks a merely inconclusive probe.
     """
     if early:
         return early
@@ -85,22 +87,21 @@ def _build_reason_code(
         return "disposable"
     if dns is not None and dns.a_fallback and not dns.has_mx_records:
         return "a_fallback_only"
+    if smtp is not None and smtp.verified is False and smtp.smtp_code:
+        if smtp.smtp_code >= 500:
+            return "rcpt_5xx"
+        if smtp.smtp_code >= 400:
+            return "rcpt_4xx"
+        if smtp.smtp_code >= 200:
+            return "rcpt_2xx"
     if catch_all is not None and catch_all.is_catch_all:
         return "catch_all_detected"
-    if smtp is not None:
-        if smtp.verified is False and smtp.smtp_code:
-            if smtp.smtp_code >= 500:
-                return "rcpt_5xx"
-            if smtp.smtp_code >= 400:
-                return "rcpt_4xx"
-            if smtp.smtp_code >= 200:
-                return "rcpt_2xx"
-        if smtp.verified is None and smtp.error:
-            return (
-                "smtp_timeout"
-                if re.search(r"timed?\s*out", smtp.error, re.IGNORECASE)
-                else "smtp_unavailable"
-            )
+    if smtp is not None and smtp.verified is None and smtp.error:
+        return (
+            "smtp_timeout"
+            if re.search(r"timed?\s*out", smtp.error, re.IGNORECASE)
+            else "smtp_unavailable"
+        )
     return None
 
 

tests/test_engine_metadata.py

@@ -165,6 +165,42 @@ class EngineMetadataTests(unittest.IsolatedAsyncioTestCase):
         self.assertEqual(result.reason_code, "catch_all_detected")
         self.assertEqual(result.status, ValidationStatus.RISKY)
 
+    async def test_explicit_5xx_rejection_outranks_catch_all(self):
+        # A definitive "mailbox does not exist" (5xx) is stronger and more
+        # actionable than the domain-level catch-all flag: reporting catch_all
+        # beside status=invalid is incoherent. The explicit rejection must win.
+        engine = EmailValidationEngine()
+        with (
+            patch("app.validator.engine.validate_syntax", return_value=_syntax()),
+            patch(
+                "app.validator.engine.check_dns",
+                new=AsyncMock(return_value=_dns()),
+            ),
+            patch(
+                "app.validator.engine.check_disposable",
+                return_value=_disposable(),
+            ),
+            patch(
+                "app.validator.mailbox_provider.smtp_verifier.verify",
+                new=AsyncMock(
+                    return_value=SMTPResult(
+                        verified=False,
+                        smtp_code=550,
+                        smtp_message="550 mailbox does not exist (provider confirmed)",
+                    )
+                ),
+            ),
+            patch(
+                "app.validator.mailbox_provider.smtp_verifier.check_catch_all",
+                new=AsyncMock(return_value=(True, 0.95)),
+            ),
+        ):
+            result = await engine.validate("person@example.test", deep=True)
+
+        self.assertEqual(result.reason_code, "rcpt_5xx")
+        self.assertEqual(result.scoring.score, 0)
+        self.assertEqual(result.status, ValidationStatus.INVALID)
+
     async def test_reason_code_smtp_timeout(self):
         engine = EmailValidationEngine()
         with (