fix: preserve locality and unit evidence without header noise

Author: javaDevJT

docs/general-address-reliability-2026-10-19.md

@@ -50,14 +50,21 @@ or the street-to-city join. Nearby uncertain unit fragments remain evidence and
 still require review. Strict consensus packet validation and all three engines
 remain intact.
 
+Only validated state codes form standalone state boundaries. Unknown short OCR
+fragments cannot prematurely terminate the following city line. Backward evidence
+collection requires vertical overlap, or an adjacent nearby plausible unit token
+(mixed letters/digits or an explicit unit marker, bounded to 32 characters).
+This keeps unrelated header artifacts out of the first address while preserving
+uncertain unit evidence.
+
 Geocoding `street-address-v7` invalidates older location metadata in cache/session
 validation. Recovered rows show Google's map address and retain the original
 address text. Unit verification and building-only verification remain distinct;
 the normal retry/loading/success feedback and uncertain-command holds remain.
 
 ## Validation and release
 
-- Clean package: 228 Java tests passed, including 36 name/state/unit combinations
+- Clean package: 231 Java tests passed, including 36 name/state/unit combinations
   and rejection/proof-budget tests. All 36 frontend tests passed, including v5/v6
   saved-session migration and safe rendering of provider text.
 - Eleven user-authorized Google diagnostics were recorded privately. Replaying

src/main/java/com/jtdev/routelisttotesla/service/AddressOcrService.java

@@ -66,7 +66,6 @@ public class AddressOcrService {
     private static final Pattern STATE_SUFFIX = Pattern.compile(
             "(?i)(?:^|[,\\s])(?:AL|AK|AZ|AR|CA|CO|CT|DE|DC|FL|GA|HI|ID|IL|IN|IA|KS|KY|LA|ME|MD|MA|MI|MN|MS|MO|MT|NE|NV|NH|NJ|NM|NY|NC|ND|OH|OK|OR|PA|RI|SC|SD|TN|TX|UT|VT|VA|WA|WV|WI|WY|PR|GU|VI|AS|MP|ALABAMA|ALASKA|ARIZONA|ARKANSAS|CALIFORNIA|COLORADO|CONNECTICUT|DELAWARE|FLORIDA|GEORGIA|HAWAII|IDAHO|ILLINOIS|INDIANA|IOWA|KANSAS|KENTUCKY|LOUISIANA|MAINE|MARYLAND|MASSACHUSETTS|MICHIGAN|MINNESOTA|MISSISSIPPI|MISSOURI|MONTANA|NEBRASKA|NEVADA|NEW\\s+HAMPSHIRE|NEW\\s+JERSEY|NEW\\s+MEXICO|NEW\\s+YORK|NORTH\\s+CAROLINA|NORTH\\s+DAKOTA|OHIO|OKLAHOMA|OREGON|PENNSYLVANIA|RHODE\\s+ISLAND|SOUTH\\s+CAROLINA|SOUTH\\s+DAKOTA|TENNESSEE|TEXAS|UTAH|VERMONT|VIRGINIA|WASHINGTON|WEST\\s+VIRGINIA|WISCONSIN|WYOMING)(?:[,\\s]+\\d{5}(?:-\\d{4})?)?(?:[,\\s]+(?:USA|UNITED\\s+STATES))?\\s*$");
     private static final Pattern ZIP_SUFFIX = Pattern.compile("\\b\\d{5}(?:-\\d{4})?\\s*$");
-    private static final Pattern STATE_ONLY_LINE = Pattern.compile("(?i)^\\s*[A-Z]{2}(?:\\s+\\d{5}(?:-\\d{4})?)?\\s*$");
     private static final Pattern UNIT_LINE = Pattern.compile("(?i)^" + AddressExtractor.UNIT_LABELS + "\\s*#?\\s*[\\p{L}\\p{N}-]*\\s*$");
     private static final Pattern UNIT_MARKER_END = Pattern.compile("(?i)(?:^|\\s)" + AddressExtractor.UNIT_LABELS + "\\s*$");
     private static final Pattern UNIT_VALUE = Pattern.compile("(?i)^#?[\\p{L}\\p{N}][\\p{L}\\p{N}-]*$");
@@ -191,9 +190,22 @@ public List<PlaceCandidate> extractAddressCandidates(byte[] imageBytes, String n
                 for (int previousLineIndex = lineIndex - 1; previousLineIndex >= 0; previousLineIndex--) {
                     OcrLine previous = lines.get(previousLineIndex);
                     String previousText = previous.text().trim();
-                    if (!linesAreVerticallyAdjacentOrOverlapping(previous, line) || previousText.length() > 3
+                    boolean verticalOverlap = previous.bottom() > line.top();
+                    boolean horizontallyNear = linesAreHorizontallyNear(previous, line);
+                    boolean mixedAlphaNumericUnit = UNIT_VALUE.matcher(previousText).matches()
+                            && previousText.chars().anyMatch(Character::isLetter)
+                            && previousText.chars().anyMatch(Character::isDigit);
+                    boolean numericUnitAfterMarker = UNIT_MARKER_END.matcher(addressText).find()
+                            && UNIT_VALUE.matcher(previousText).matches();
+                    boolean adjacentNearbyUnit = !verticalOverlap
+                            && linesAreAdjacent(previous, line)
+                            && horizontallyNear
+                            && previousText.length() <= 32
+                            && (mixedAlphaNumericUnit || numericUnitAfterMarker);
+                    if ((!verticalOverlap && !adjacentNearbyUnit)
+                            || (previousText.length() > 3 && !adjacentNearbyUnit)
                             || addressCandidateText(previousText) != null || isStateOnlyLine(previousText)) break;
-                    if (linesAreHorizontallyNear(previous, line)) {
+                    if (horizontallyNear) {
                         nearbyFragmentRequiresReview = true;
                         evidenceLineIndexes.add(previousLineIndex);
                     }
@@ -637,8 +649,7 @@ private static String adjacentLocality(OcrLine addressLine, OcrLine followingLin
     }
 
     private static boolean isStateOnlyLine(String text) {
-        return text != null && (STATE_ONLY_LINE.matcher(text.trim()).matches()
-                || AddressExtractor.isStateOnlyLine(text));
+        return text != null && AddressExtractor.isStateOnlyLine(text);
     }
 
     static String addressCandidateText(String text) {

src/test/java/com/jtdev/routelisttotesla/service/AddressOcrServiceTest.java

@@ -193,25 +193,98 @@ void retainsAdjacentNonOverlappingNearbyUnitFragmentAsReviewEvidence() throws Ex
     }
 
     @Test
-    void retainsAdjacentNonOverlappingNearbyUnitFragmentBeforeAddressAsReviewEvidence() throws Exception {
+    void excludesAdjacentNonOverlappingHeaderFragmentsFromAddressEvidence() throws Exception {
         String tsv = TSV_HEADER + "\n" + String.join("\n",
-                "5\t1\t1\t1\t1\t1\t410\t70\t20\t10\t90\t3B",
-                "5\t1\t1\t1\t2\t1\t100\t100\t300\t20\t90\t123 MAIN ST",
-                "5\t1\t1\t1\t3\t1\t100\t140\t120\t20\t90\tDETROIT");
+                "5\t1\t1\t1\t1\t1\t100\t70\t40\t10\t90\teG»",
+                "5\t1\t1\t1\t2\t1\t100\t82\t30\t10\t90\t929",
+                "5\t1\t1\t1\t3\t1\t100\t100\t300\t20\t90\t123 MAIN ST",
+                "5\t1\t1\t1\t4\t1\t100\t140\t120\t20\t90\tDETROIT");
         Map<String, Object> lineEvidence = Map.of(
-                "1", evidence(1, true, List.of(reading("easyocr", "3B"))),
-                "2", consensusEvidence("123 MAIN ST"),
-                "3", consensusEvidence("DETROIT"));
+                "1", evidence(1, true, List.of(reading("tesseract", "eG»"))),
+                "2", evidence(1, true, List.of(reading("tesseract", "929"))),
+                "3", consensusEvidence("123 MAIN ST"),
+                "4", consensusEvidence("DETROIT"));
         String output = consensusOutput(tsv, lineEvidence);
         AddressOcrService service = new AddressOcrService("ocr-binary", "eng",
                 ignored -> new AddressOcrService.ProcessResult(0, output, ""), false);
 
         PlaceCandidate candidate = service.extractAddressCandidates(png(), "route.png", "").get(0);
 
         assertEquals("123 MAIN ST, DETROIT", candidate.text());
+        assertEquals(3, candidate.ocrAgreement());
+        assertFalse(candidate.ocrReviewRequired());
+        assertTrue(candidate.ocrAlternatives().stream().noneMatch(value -> value.startsWith("line 1 ")
+                || value.startsWith("line 2 ")));
+    }
+
+    @Test
+    void retainsAdjacentNonOverlappingNearbyUnitFragmentBeforeAddressAsReviewEvidence() throws Exception {
+        for (String unit : List.of("3B", "A208")) {
+            String tsv = TSV_HEADER + "\n" + String.join("\n",
+                    "5\t1\t1\t1\t1\t1\t410\t70\t20\t10\t90\t" + unit,
+                    "5\t1\t1\t1\t2\t1\t100\t100\t300\t20\t90\t123 MAIN ST",
+                    "5\t1\t1\t1\t3\t1\t100\t140\t120\t20\t90\tDETROIT");
+            Map<String, Object> lineEvidence = Map.of(
+                    "1", evidence(1, true, List.of(reading("easyocr", unit))),
+                    "2", consensusEvidence("123 MAIN ST"),
+                    "3", consensusEvidence("DETROIT"));
+            String output = consensusOutput(tsv, lineEvidence);
+            AddressOcrService service = new AddressOcrService("ocr-binary", "eng",
+                    ignored -> new AddressOcrService.ProcessResult(0, output, ""), false);
+
+            PlaceCandidate candidate = service.extractAddressCandidates(png(), "route.png", "").get(0);
+
+            assertEquals("123 MAIN ST, DETROIT", candidate.text());
+            assertEquals(1, candidate.ocrAgreement());
+            assertTrue(candidate.ocrReviewRequired());
+            assertTrue(candidate.ocrAlternatives().contains("line 1 easyocr: " + unit));
+        }
+    }
+
+    @Test
+    void keepsAdjacentPlainNumericFragmentOnlyWhenAddressHasUnitMarker() throws Exception {
+        for (String unit : List.of("929", "2018")) {
+            String tsv = TSV_HEADER + "\n" + String.join("\n",
+                    "5\t1\t1\t1\t1\t1\t100\t82\t30\t10\t90\t" + unit,
+                    "5\t1\t1\t1\t2\t1\t100\t100\t300\t20\t90\t123 MAIN ST APT",
+                    "5\t1\t1\t1\t3\t1\t100\t140\t120\t20\t90\tDETROIT, MI");
+            Map<String, Object> lineEvidence = Map.of(
+                    "1", evidence(1, true, List.of(reading("tesseract", unit))),
+                    "2", consensusEvidence("123 MAIN ST APT"),
+                    "3", consensusEvidence("DETROIT, MI"));
+            String output = consensusOutput(tsv, lineEvidence);
+            AddressOcrService service = new AddressOcrService("ocr-binary", "eng",
+                    ignored -> new AddressOcrService.ProcessResult(0, output, ""), false);
+
+            PlaceCandidate candidate = service.extractAddressCandidates(png(), "route.png", "").get(0);
+
+            assertEquals("123 MAIN ST APT, DETROIT, MI", candidate.text());
+            assertEquals(1, candidate.ocrAgreement());
+            assertTrue(candidate.ocrReviewRequired());
+            assertTrue(candidate.ocrAlternatives().contains("line 1 tesseract: " + unit));
+        }
+    }
+
+    @Test
+    void retainsUnknownAdjacentTwoLetterFragmentSoFollowingLocalityStillJoins() throws Exception {
+        String tsv = TSV_HEADER + "\n" + String.join("\n",
+                "5\t1\t1\t1\t1\t1\t100\t100\t300\t20\t90\t22 1/2 EASTRIDGE CT",
+                "5\t1\t1\t1\t2\t1\t100\t124\t30\t10\t90\tNN",
+                "5\t1\t1\t1\t3\t1\t100\t140\t120\t20\t90\tALBANY NY");
+        Map<String, Object> lineEvidence = Map.of(
+                "1", consensusEvidence("22 1/2 EASTRIDGE CT"),
+                "2", evidence(1, true, List.of(reading("tesseract", "NN"))),
+                "3", consensusEvidence("ALBANY NY"));
+        String output = consensusOutput(tsv, lineEvidence);
+        AddressOcrService service = new AddressOcrService("ocr-binary", "eng",
+                ignored -> new AddressOcrService.ProcessResult(0, output, ""), false);
+
+        PlaceCandidate candidate = service.extractAddressCandidates(png(), "route.png", "").get(0);
+
+        assertEquals("22 1/2 EASTRIDGE CT, ALBANY NY", candidate.text());
         assertEquals(1, candidate.ocrAgreement());
         assertTrue(candidate.ocrReviewRequired());
-        assertTrue(candidate.ocrAlternatives().contains("line 1 easyocr: 3B"));
+        assertTrue(candidate.ocrAlternatives().contains("line 2 tesseract: NN"));
     }
 
     @Test