Polish passport number

What it covers

Returns a valid Polish passport number (numer paszportu) with a correct checksum. Use `format` to choose between compact and space-separated rendering. Set `invalid=true` to get a passport number with a deliberately wrong check digit, for testing checksum validators.

How it’s calculated

A single decimal check digit sits at position 3 of the nine-character passport number (right after the two series letters); it is chosen so the weighted sum over all nine characters, with letters valued A=10…Z=35, is congruent to 0 modulo 10.

Nine-character layout with placeholder at the check position: A, B, C, 1, 2, 3, 4, 5, 6 (indices 0..8).
Weights by index: [7, 3, 9, 1, 7, 3, 1, 7, 3].
Character values: A=10, B=11, then digits 1,2,3,4,5,6 keep their own values.
Weighted contributions of the eight non-check positions: A(10)*7=70; B(11)*3=33; d3=1*1=1; d4=2*7=14; d5=3*3=9; d6=4*1=4; d7=5*7=35; d8=6*3=18.
Sum of non-check contributions S = 70+33+1+14+9+4+35+18 = 184.
Check position weight is 9, so we need (184 + 9*C) mod 10 == 0. Since 184 mod 10 = 4, we need (4 + 9*C) mod 10 == 0, i.e. 9*C ≡ 6 (mod 10).
Scanning C=0..9: C=4 gives 9*4=36 ≡ 6 (mod 10). Total = 184 + 36 = 220, and 220 mod 10 = 0. So C = 4.
No smaller candidate works: C=0→184(4), C=1→193(3), C=2→202(2), C=3→211(1), C=4→220(0) ✓.

Edge cases

• The check digit is not appended at the end — it is the third character of the nine-character string, immediately after the two series letters (zero-based index 2).
• Both series letters participate in the checksum with their alphabetic values (A=10 … Z=35), not just the digits, so the two leading letters affect the required check digit.

Gotchas

• characterValue throws on any character that is not an uppercase A–Z letter or a single digit, so malformed input fails fast rather than silently producing a wrong sum.
• Because the check position's weight (9) is coprime with 10, exactly one check digit in 0–9 satisfies the mod-10 congruence; the generator finds it by a simple 0–9 scan rather than a closed-form complement.
• The mod-10 rule means the full weighted sum (including the check digit) is ≡ 0 mod 10 — there is no 10-minus-remainder complement step and no residue that maps to a non-digit, so every position is always fillable with a plain 0–9 digit.