@trustchex/react-native-sdk 1.472.0 → 1.475.1

package/src/Shared/Libs/MRZ_KNOWN_ISSUES.md

@@ -0,0 +1,112 @@
+# MRZ Reading & Correction — Known Issues & Limitations
+
+This documents the **inherent limitations** and **deliberate trade-offs** of the
+MRZ camera scanner (`mrz.utils.ts`, `mrzFrameAggregator.ts`, and the native
+`TrustchexCameraView` scan-frame OCR). These are not bugs — they are constraints
+of the ICAO 9303 standard and OCR, and the design decisions made around them.
+
+For the camera/OCR pipeline overview, see the doc comments in
+`mrzFrameAggregator.ts` and `mrz.utils.ts`.
+
+---
+
+## 1. Check-digit MOD-10 collisions: `1↔L` and `6↔G` are indistinguishable
+
+**Issue.** ICAO's 7-3-1 check digit weights letters by value (`A`=10 … `Z`=35),
+then takes the result mod 10. Some OCR look-alikes are **mod-10 equal** to the
+digit they resemble:
+
+| Look-alike | Letter value | Digit | mod 10 |
+| --- | --- | --- | --- |
+| `L` ↔ `1` | 21 | 1 | both ≡ **1** |
+| `G` ↔ `6` | 16 | 6 | both ≡ **6** |
+
+So a document number read as `SPECL2345` produces the **exact same check digit**
+as the correct `SPEC12345`. The MRZ **validates either way** — the check digit
+cannot tell them apart.
+
+**Impact.** If OCR reads a `1` as `L` (or `6` as `G`) in a *numeric* position of a
+field that also accepts letters (e.g. an alphanumeric document number), the MRZ
+will validate but may carry the letter form.
+
+**Mitigation.**
+
+- **Multi-frame voting** (`mrzFrameAggregator`) usually resolves it: across frames
+  the correct glyph wins the per-character vote.
+- **NFC chip read (eID)** is authoritative — when available it overrides the
+  camera reading.
+- Other digit↔letter confusions (`0↔O/Q/D`, `2↔Z`, `5↔S`, `8↔B`, `4↔A`, `1↔I`) are
+  **not** mod-10 collisions and *are* recovered to the correct digit.
+
+Covered by `mrz.ambiguous.test.ts` ("documents the … MOD-10 collision").
+
+---
+
+## 2. Unprotected fields (TD1 optional / national-ID) can't be self-corrected
+
+**Issue.** TD1's optional-data field (which on Turkish IDs holds the 11-digit
+national ID / TC number) has **no per-field check digit** — it is only covered by
+the composite check digit. If OCR corrupts the optional field **and** the
+composite digit is also dropped/misread (common on glossy cards), there is no
+independent anchor to detect the error.
+
+**Mitigation.** High-confidence numeric normalisation (`B→8`, `S→5`, `O→0`, …) is
+applied to the all-digit optional field, and **multi-frame voting** is the
+primary safeguard. A single noisy frame is not trusted; the consensus is.
+
+---
+
+## 3. Filler-letter normalisation is conservative in name fields (by design)
+
+**Issue.** The `<` filler is frequently OCR'd as a letter (`K`, and under glare
+`C`/`E`/`G`). We normalise these back to `<` **only** in structurally
+unambiguous positions — the trailing filler run, the TD1 issuing-state field, and
+the document-code filler.
+
+**Deliberate trade-off.** A `K`/`C`/`E`/`G` **inside the name field** is *not*
+normalised, because it cannot be distinguished from a real name letter (surnames
+like `AKTAS`, `KAYA`, `CETIN`, or a 2-letter `AK` start with these). Corrupting a
+real name is worse than a cosmetic filler glyph, so:
+
+- Names are **preserved verbatim** — `AKTAS` stays `AKTAS`.
+- A genuine filler misread *in the middle of a name region* may remain as a
+  letter (cosmetic only; the name field has no check digit, so validity is
+  unaffected, and the document number / dates — the identity-critical fields —
+  are always cleaned).
+
+Covered by the "real letters in names are not eaten" tests in `mrz.utils.test.ts`.
+
+---
+
+## 4. OCR throughput / image-quality dependence
+
+- **Resolution.** ML Kit needs ~16 px per character. A full-frame capture leaves a
+  30–44-char MRZ line below that floor, so the native pipeline **crops to the
+  on-screen scan frame and upscales + grayscale/contrast-enhances** before OCR.
+  The MRZ band must be reasonably filled within the on-screen guide.
+- **Glare / lamination.** Heavy glare on a glossy laminated card still degrades
+  OCR; the enhancement helps but does not eliminate it. Steadying the card and
+  reducing direct glare improves convergence.
+- **Throughput.** OCR runs at a few frames/sec; the JS handler is throttled
+  (~400 ms) and the recovery search is time-bounded so the UI stays responsive.
+  A pathological/garbage frame fails fast (recovery budget) rather than blocking.
+
+---
+
+## 5. Structurally broken frames are (correctly) rejected
+
+Truncated or wrong-length line-sets that cannot be repaired by ambiguous-char
+swaps or ±1 indel are reported **invalid** — the flow will not advance on a
+guess. This is intentional: a wrong-but-plausible reconstruction must never leak
+through. Multi-frame scanning accumulates until a check-digit-valid consensus is
+reached.
+
+---
+
+## 6. Platform parity
+
+The scan-frame ROI crop + grayscale/contrast enhancement exists on **both Android
+(Kotlin) and iOS (Swift / Core Image)**. The JS recovery, voting, and field
+mapping are shared, so behaviour is consistent across platforms. Debug builds
+require Metro to be reachable; build a **Release** variant for untethered device
+testing.