fix: corroborate address recovery and isolate OCR metadata

Author: javaDevJT

docs/README.md

@@ -1,5 +1,7 @@
 # Documentation
 
+- [General address reliability (2026-10-19)](general-address-reliability-2026-10-19.md): bounded provider-corroborated recovery, OCR layout boundaries and release checks.
+
 - [Apartment lookup and OCR evidence (2026-10-18)](southfield-address-and-ocr-evidence-2026-10-18.md): provider unit-label normalization, spatial metadata exclusion and saved-location migration.
 
 - [Street suffix and township recovery (2026-10-17)](address-aliases-2026-10-17.md): deployed comprehensive USPS catalog, supplied HEIC diagnosis, final native qualification and release proof.

docs/development-reference.md

@@ -4,6 +4,20 @@ TAP-managed sign-in and stable-subject authorization replace independent Google
 
 ## Source flow
 
+### October 19 provider-corroborated recovery
+
+Current extraction is `ocr-consensus-v9`; geocoding is `street-address-v7`.
+Spatial evidence also excludes vertically adjacent side counters while retaining
+nearby ambiguous unit fragments. Geocoding first applies strict matching, then
+can corroborate a unique precise candidate through reverse locality verification
+or constrained-original plus canonical street queries. No address-specific
+replacement mappings are used. House numbers, street-name letters, directions,
+unit conflicts, state/country, partial/city results and ambiguity remain guarded.
+Recovered results expose Google's map address while retaining input text and
+the distinction between a verified unit and a verified building. Saved results
+under earlier policies are revalidated. See the
+[recovery contract and checks](general-address-reliability-2026-10-19.md).
+
 ### October 18 spatial OCR evidence
 
 Extraction version `ocr-consensus-v8` separates short package counters from

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

@@ -0,0 +1,79 @@
+# General address reliability
+
+The October 19 report exposed two geocoding representation differences and a
+deployment gap. Production still served the October 17 image, so the spatial
+OCR evidence fix pushed on October 18 had not reached the running application.
+The supplied original HEIC was converted and visually inspected; under the newer
+parser, all six street/unit lines already had three-engine agreement without
+package-counter warnings.
+
+Google's precise Hall Road result uses a different postal city. Reverse geocoding
+also returns the exact requested house/street/city 1.59 metres away. The Hilltop
+result uses Drive where the screenshot says Court; both its constrained original
+query and its canonical query return the same rooftop place ID. These are
+observations from private diagnostic responses, not address replacement rules.
+
+## General recovery contract
+
+Strict street matching remains the fast path. Recovery can propose only a unique,
+non-partial rooftop street-level result with the requested house number, street
+name, directions, state and country. The input must include city and state. Only
+one semantic dimension may differ:
+
+- If no recognized locality level explicitly corroborates the requested city,
+  reverse geocoding must return a full matching house/street/locality address
+  within ten metres. A city, county, postal-code centre or nearby different house
+  cannot supply that proof. The original rooftop location remains the target.
+- For a different street type or compound-name spacing, a query containing the
+  original house/street/unit and structured locality must return the proposed
+  same rooftop place ID. A second query containing the canonical street must
+  corroborate it again, within two metres. A competing same-number/stem destination
+  in either proof blocks correction, regardless of result order.
+
+Recovery never rewrites house numbers, street-name letters, directions, apartment
+identifiers, state or country. It cannot combine city and street corrections.
+Missing or conflicting provider components, partial matches, invalid coordinates,
+ambiguous destinations and genuine unit conflicts remain guarded. Verification
+of a recovered apartment requires matching unit evidence in the proposal and
+proofs; otherwise only the building is verified and the apartment is retained.
+
+Proof queries share the existing eight-request stop ceiling, 25-second stop and
+90-second batch deadlines, per-owner/global budgets, transient retries and 60 ms
+global request pacing. They do not use a separate unlimited retry path. No
+per-address lookup table, hosted OCR or OpenAI key is introduced.
+
+## OCR, feedback and saved results
+
+Extraction `ocr-consensus-v9` also handles a far-column short counter that is
+vertically adjacent rather than overlapping: it cannot interrupt a wrapped unit
+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.
+
+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
+  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
+  those bodies through the actual geocoder verifies all six supplied rows in
+  order while preserving address text: nine fixture requests, no external calls
+  or vehicle commands. Hall uses two requests; Hilltop uses three.
+- Native baseline on the original HEIC and the prior Southfield screenshot:
+  eight exact rows, 3/3 address agreement, no false review warnings, 36 Python
+  tests passed, and disposable QA app/fixtures cleaned up. This baseline used
+  source overlays and is not final-image qualification.
+
+Final image qualification and deployment evidence will be recorded after the
+source CI, security/storage/publication gates and immutable image checks finish.
+No vehicle commands are part of validation. Credentials, original delivery
+screenshots and provider bodies remain outside source control. Existing data,
+TAP authorization, CSRF, ordering/dedupe and eight-stop grouping are preserved.
+
+API references: Google's [forward geocoding response contract](https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding)
+and [reverse-geocoding contract](https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-reverse-geocoding).

src/main/java/com/jtdev/routelisttotesla/model/LocationResolution.java

@@ -7,7 +7,13 @@ public record LocationResolution(
         String reasonCode,
         int attempts,
         String policyVersion,
-        Integer retryAfterSeconds) {
+        Integer retryAfterSeconds,
+        String matchedAddress) {
+
+    public LocationResolution(Status status, String strategy, String reasonCode, int attempts,
+                              String policyVersion, Integer retryAfterSeconds) {
+        this(status, strategy, reasonCode, attempts, policyVersion, retryAfterSeconds, null);
+    }
 
     public enum Status {
         VERIFIED_UNIT, VERIFIED_BUILDING, NO_MATCH, AMBIGUOUS, DEFERRED, LOOKUP_UNAVAILABLE

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

@@ -46,7 +46,7 @@
 
 @Service
 public class AddressOcrService {
-    public static final String EXTRACTION_VERSION = "ocr-consensus-v8";
+    public static final String EXTRACTION_VERSION = "ocr-consensus-v9";
 
     static final int MAX_IMAGE_BYTES = 12 * 1024 * 1024;
     static final long MAX_IMAGE_PIXELS = 20_000_000L;
@@ -185,15 +185,16 @@ public List<PlaceCandidate> extractAddressCandidates(byte[] imageBytes, String n
 
                 int lastLineIndex = lineIndex;
                 int lastAddressLineIndex = lineIndex;
-                boolean overlappingFragment = false;
+                boolean nearbyFragmentRequiresReview = false;
                 List<Integer> evidenceLineIndexes = new ArrayList<>();
                 evidenceLineIndexes.add(lineIndex);
                 for (int previousLineIndex = lineIndex - 1; previousLineIndex >= 0; previousLineIndex--) {
                     OcrLine previous = lines.get(previousLineIndex);
-                    if (previous.bottom() <= line.top() || previous.text().trim().length() > 3
-                            || addressCandidateText(previous.text()) != null) break;
+                    String previousText = previous.text().trim();
+                    if (!linesAreVerticallyAdjacentOrOverlapping(previous, line) || previousText.length() > 3
+                            || addressCandidateText(previousText) != null || isStateOnlyLine(previousText)) break;
                     if (linesAreHorizontallyNear(previous, line)) {
-                        overlappingFragment = true;
+                        nearbyFragmentRequiresReview = true;
                         evidenceLineIndexes.add(previousLineIndex);
                     }
                 }
@@ -204,16 +205,18 @@ public List<PlaceCandidate> extractAddressCandidates(byte[] imageBytes, String n
                     String continuation = nextLine.text().trim();
                     boolean addressContinuation = isAddressContinuation(addressText, continuation);
                     boolean smallFragment = continuation.length() <= 3
-                            && addressCandidateText(continuation) == null;
-                    boolean verticalOverlap = nextLine.top() < previousLine.bottom();
-                    boolean smallOverlap = smallFragment && verticalOverlap
-                            && linesAreHorizontallyNear(previousLine, nextLine);
-                    if (smallFragment && verticalOverlap && !smallOverlap) {
+                            && addressCandidateText(continuation) == null
+                            && !isStateOnlyLine(continuation);
+                    boolean verticallyConnected = linesAreVerticallyAdjacentOrOverlapping(previousLine, nextLine);
+                    boolean horizontallyNear = linesAreHorizontallyNear(previousLine, nextLine);
+                    boolean nearbyShortFragment = smallFragment && verticallyConnected && horizontallyNear;
+                    boolean sideColumnShortFragment = smallFragment && verticallyConnected && !horizontallyNear;
+                    if (sideColumnShortFragment) {
                         // Skip side-column metadata but keep looking from the last address line.
                         nextLineIndex++;
                         continue;
                     }
-                    if (!linesAreAdjacent(previousLine, nextLine) && !smallOverlap) {
+                    if (!linesAreAdjacent(previousLine, nextLine) && !nearbyShortFragment) {
                         break;
                     }
                     if (addressContinuation) {
@@ -222,9 +225,9 @@ public List<PlaceCandidate> extractAddressCandidates(byte[] imageBytes, String n
                         lastAddressLineIndex = nextLineIndex;
                         evidenceLineIndexes.add(lastLineIndex);
                         nextLineIndex++;
-                    } else if (smallOverlap) {
+                    } else if (nearbyShortFragment) {
                         // A nearby short fragment may be an unlabelled unit, so keep it reviewable.
-                        overlappingFragment = true;
+                        nearbyFragmentRequiresReview = true;
                         lastLineIndex = nextLineIndex;
                         lastAddressLineIndex = nextLineIndex;
                         evidenceLineIndexes.add(lastLineIndex);
@@ -282,7 +285,7 @@ && isStateOnlyLine(stateLine.text())
                         0,
                         null,
                         ocrEvidence.agreement(),
-                        overlappingFragment || ocrEvidence.reviewRequired(),
+                        nearbyFragmentRequiresReview || ocrEvidence.reviewRequired(),
                         ocrEvidence.alternatives()));
                 lineIndex = lastLineIndex;
             }
@@ -651,8 +654,12 @@ private static boolean linesAreAdjacent(OcrLine first, OcrLine second) {
         return gap >= -overlap && gap <= Math.max(12, (int) Math.ceil(lineHeight * 1.5));
     }
 
+    private static boolean linesAreVerticallyAdjacentOrOverlapping(OcrLine first, OcrLine second) {
+        return second.top() < first.bottom() || linesAreAdjacent(first, second);
+    }
+
     private static boolean linesAreHorizontallyNear(OcrLine first, OcrLine second) {
-        // Badge-column text can overlap an address vertically; short fragments must also sit in its text column.
+        // Short fragments can be vertically adjacent; require them to sit in the address text column.
         int gap = Math.max(0, Math.max(first.left() - second.right(), second.left() - first.right()));
         int lineHeight = Math.max(first.bottom() - first.top(), second.bottom() - second.top());
         return gap <= Math.max(12, (int) Math.ceil(lineHeight * 1.5));