1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
//! What a check digit provably *cannot* catch.
//!
//! The closed-form law, its inversion of the usual OCR intuition, and what
//! changes once a misread spans more than one character are documented on
//! [`Blindspot`], which is the public face of this module.
use cratechar_value;
/// Whether a check digit can distinguish two MRZ characters.
///
/// An ICAO 9303 check digit (Part 3 §4.9) is the 7-3-1 weighted sum of the
/// character values `0-9 → 0-9`, `A-Z → 10-35`, `< → 0`, taken **mod 10**.
/// A single-character substitution shifts the sum by
/// `weight × (value(a) - value(b))`, and that shift vanishes mod 10 for
/// *every* weight exactly when the two values are congruent mod 10.
///
/// That gives a complete, closed-form law:
///
/// > Two MRZ characters are indistinguishable to every check digit **iff**
/// > their ICAO values are congruent mod 10.
///
/// The consequence inverts most people's intuition. The OCR confusions that
/// get worried about most — O↔0, I↔1, B↔8, S↔5, Z↔2 — are all **caught**,
/// because letters sit 10..35 and their digit lookalikes do not line up mod
/// 10. The quiet pairs K↔`<`, I↔S, B↔L and A↔K are **blind**, and no amount
/// of check-digit arithmetic will ever separate them.
///
/// ```
/// use mrz::{blindspot, Blindspot};
///
/// // The classic OCR worry is not the dangerous one.
/// assert!(matches!(blindspot('O', '0'), Blindspot::Caught { .. }));
/// // This one is invisible to every check digit ever printed.
/// assert!(blindspot('K', '<').is_blind());
/// ```
///
/// [`CLASSES`] is the complete atlas of the blind pairs, and
/// `cargo run -p mrz --example checksum_blindspots` demonstrates the same law
/// empirically against the real parser rather than asserting the algebra.
///
/// # The law is pairwise; real misreads usually are not
///
/// Everything above is stated for **one** substituted character, which is what
/// [`blindspot`] takes and all this type can express. Measured against a real
/// corpus, only about a third of document-number misreads are single-character
/// (25 of 76; see
/// `knowledge/benchmarks/checksum-blindspots-measured-2026-08-05.md`).
///
/// Across k substituted positions the sum shifts by `Σ Δᵢ·wᵢ (mod 10)`, so
/// individually-**caught** substitutions cancel one another. The common case is
/// two O↔0 at weights 7 and 3: `24·(7+3) = 240 ≡ 0`. Separately each is caught
/// (`24·7 ≡ 8`, `24·3 ≡ 2`); together they are invisible. In a 9-character
/// document number the weights run 7,3,1,7,3,1,7,3,1, so that (7,3) pairing
/// joins any of the weight-7 positions 0, 3, 6 to any of the weight-3
/// positions 1, 4, 7: nine of the 36 position pairs — structural, not a fluke.
/// A shared shift of 5, such as two `2`↔`7` misreads, cancels at every pair,
/// because the sum of two odd weights is even.
///
/// So read the law as *"which single swaps are safe"*, not as *"which
/// characters are safe"*. Empirically the undetectable set is dominated by the
/// pairs it calls caught — O↔0 alone accounts for 44 of those 76 rows —
/// precisely because they arrive in combinations. Of the quiet pairs named as
/// the real danger, exactly one K↔`<` appears in the whole corpus.
///
/// This is why the crate layers structural guards on top of the arithmetic
/// (country-code recognition and date plausibility in the scanner
/// repair gates; direct `parse_*` calls do not apply those guards): the oracle is
/// exact, and it is exact about its own edges too. It is a strong *filter* — it
/// rejects most misreads — and a weak *oracle*: what it passes is not a random
/// remainder but specifically what the arithmetic cannot see.
///
/// Obtain one from [`blindspot`]. `#[non_exhaustive]`: a future variant (e.g.
/// for a format whose check digit is not mod 10) must not be a breaking change.
/// Classify a single-character substitution: can any ICAO check digit tell
/// `a` from `b`?
///
/// ```
/// use mrz::{blindspot, Blindspot};
///
/// assert_eq!(blindspot('A', 'A'), Blindspot::Identical);
/// assert_eq!(blindspot('A', 'K'), Blindspot::Blind { residue: 0 });
/// assert_eq!(blindspot('O', '0'), Blindspot::Caught { delta_mod10: 4 });
/// assert_eq!(blindspot('a', 'A'), Blindspot::NotMrzCharset);
/// ```
/// The ten residue classes partitioning the 37-character MRZ alphabet:
/// `CLASSES[r]` lists every character whose ICAO value is ≡ `r` (mod 10).
///
/// This is the complete atlas of undetectable substitutions — any swap
/// *within* a row is invisible to every check digit, and any swap *across*
/// rows is caught. Note class 0 has five members because `<` and `0` share
/// the value 0.
///
/// ```
/// use mrz::{blindspot, CLASSES, MRZ_ALPHABET};
///
/// // Every swap inside a row is blind ...
/// for row in CLASSES {
/// for &a in row {
/// for &b in row {
/// assert!(a == b || blindspot(a, b).is_blind());
/// }
/// }
/// }
/// // ... and the rows partition the whole 37-character alphabet.
/// assert_eq!(CLASSES.iter().map(|row| row.len()).sum::<usize>(), MRZ_ALPHABET.len());
/// ```
pub const CLASSES: = ;
/// The residue class `c` belongs to, as a borrowed row of [`CLASSES`], or
/// `None` when `c` is outside the MRZ alphabet. Allocation-free.
///
/// ```
/// // 'K' has ICAO value 20 ≡ 0 (mod 10) — the class `<`/`0` also live in.
/// assert_eq!(mrz::class_of('K'), Some(&['0', 'A', 'K', 'U', '<'][..]));
/// assert_eq!(mrz::class_of('@'), None);
/// ```
/// Every MRZ character a check digit cannot distinguish from `c`, excluding
/// `c` itself. Empty when `c` is outside the alphabet.
///
/// ```
/// use mrz::collisions;
///
/// assert_eq!(collisions('K'), vec!['0', 'A', 'U', '<']);
/// assert!(collisions('@').is_empty());
/// ```