Poland (PL): migration notes

Internal record of the P5 migration from the old scripts to the producer: the discrepancies found, their causes, and who decided what. This is a dated record, so the numbers are as of the migration and not kept current. It is not shipped in the zip.

• Issue: pc-28e.7.45 (closed 2026-10-03)
• Commit: 36df9c0 (worktree commit 09206b2, landed unchanged), batch 4
• Parity verdict: unexplained (32 unclassified cells; the gate blocks on any unclassified cell); accepted as upstream drift
• Producer: custom, refresh disabled

Sources

• The old recover_alt_names.py read nothing upstream. It copied alternate names from the legacy R2 object pl/pl.csv (an intermediate export of the old scripts/geonames/geonames_parse_to_R2.py job), pulling it from R2 with credentials (--fetch). That object isn't a real source.
• Poczta Polska's PNA register stays excluded: it is a commercial product whose terms forbid resale, the free PDF edition included (.licensing-notes.md, 2026-08-27 audit).

Parity against the live zip (2026-10-03)

Rows: 72,899 live and 72,899 fresh, none only on one side. Row order identical (the old sort was kept, so there is no row_order class). 32 changed cells, all in alternative_city_name, all unclassified. No other column differs. Before writing the producer, the agent checked the dump rule offline against the live CSV: 72,867 of 72,899 alternate names match exactly.

Cause: edits to the GeoNames dump after the legacy snapshot (upstream drift). Each changed cell maps to a dump entry modified after the legacy R2 copy was taken. 20 cells gained a name, 12 lost one.

The dump entries and dates are from the agent's trace. The per-place row breakdown was recomputed on 2026-10-05 from the live CSV and the committed data/pl.csv (it reproduces the 32 cells; the parity report lists only 10 examples).

The public sample (postal.datahub.io/pl/pl.csv) came out unexplained (informational only): 194 leading_zero_restored and 112 unclassified cells. It is the old generic GeoNames parse that turned TERYT 0201 into 201.0.

Decisions

Transforms carried over

Folded from fetch_source.py → build_base.py → recover_alt_names.py → integrity_checker.py (package.py, publish_r2.py and the scripts README deleted):

• TERYT powiat (4 digits) and gmina (6 digits) codes copied verbatim as text (no pandas 201.0).
• admin_code1 → ISO 3166-2:PL from the TERYT voivodeship prefix, not GeoNames' sequential region number (72–87). GeoNames number, TERYT prefix and region name must agree 1:1:1, and all 16 voivodeships must be present.
• Voivodeship names kept as GeoNames spells them (English exonyms, e.g. "Lower Silesia").
• Rows sorted by (admin_code1, admin_code2, postal_code, place_name).
• integrity_checker.py's checks are now ProducerErrors: NN-NNN postal codes; 4/6-digit TERYT with the gmina extending the powiat; no literal "nan" or ".0" suffix; coordinates inside Poland's bounding box; unique primary key (postal_code, place_name, admin_code3). The gmina is in the key because 78-650 Pilów is listed in two gminas (321703, 321705); both rows are kept.

Open questions

• Resolved (user, 2026-10-05, pc-28e.7.59): the D1 switch of alternative_city_name from the legacy R2 copy to the GeoNames dump is confirmed.
• .licensing-notes.md still says alternative_city_name "was recovered from the existing R2 copy rather than re-derived", which is no longer true, and it carries row counts (72,899 / 72,900 / 20,299). Left for the end-of-epic sweep (pc-hfz).

Provenance

Reconstructed 2026-10-05 from the agent transcript d33e1b7e-5027-498a-a97f-ba914ee2524e/subagents/agent-a651a38384495c267.jsonl, the orchestrator session d33e1b7e-… (hold, question, user reply, landing), session 7df0c5be-… (later citations of the pl precedent), the plan's D1 entry (session 068ca403-…), the commit message, the bd notes and close reason, and docs/parity/p5.md.