eventhub/README_COUNTRY_CODE_NORMALIZATION_PATCH.md

Country-code normalization patch

Problem found in response 202606171240 session D c home.json

The response mixed three country identifier systems:

• tachograph numeric nation codes, for example 1, 12, 13;
• tachograph alphabetic nation codes, for example A, CZ, D;
• ISO 3166-1 alpha-2 codes returned by Nominatim, for example AT, CZ, DE.

The projection contained 94 numeric country values, 33 numeric countryFrom values, and 33 numeric countryTo values. The flat and nested trip segments also contained numeric country identifiers.

This was not only a presentation problem. A tachograph value such as 13 and a Nominatim value such as DE were considered different. The supplied response contained 15 false reverse-geocoded country changes of the form 13 -> DE or 12 -> CZ, creating unnecessary country segments.

Canonical representation

All runtime country fields are now exposed and compared as ISO 3166-1 alpha-2. Examples:

Tachograph numeric	Tachograph alphabetic	Canonical ISO alpha-2
1	A	AT
12	CZ	CZ
13	D	DE

Numeric and alphabetic tachograph values are resolved through the existing TachographNationRegistry and then converted to ISO alpha-2. Nominatim results are validated and normalized as ISO values.

Processing changes

Normalization is applied before country comparison and at the main presentation boundaries:

• normalized EventHub support evidence;
• source-neutral runtime support events;
• tachograph file-session support-event adapters;
• legacy tachograph Esper result conversion;
• projection.supportGeoEvents;
• flat country-trip segments;
• country segments nested under HOME-to-HOME trips;
• Nominatim country-code parsing.

The original source payload remains available in raw event attributes where the numeric tachograph values are needed for diagnostics.

Expected result

An explicit border crossing 1 -> 13 is represented as AT -> DE. A subsequent Nominatim result DE no longer creates a false 13 -> DE transition. The trip continues in the same canonical DE country state until a genuine country change.