Fix geocoding metadata resolution under SwiftPM and per-language statement poisoning

[iziz]

Summary

• Geocoding has never worked for Swift Package Manager consumers: the metadata bundle is not where the helper looks for it, so every lookup silently returns a country name instead of a locality.
• A lookup for a country a language's database does not carry permanently disables that language for the rest of the process.
• Both are behavior fixes with no API change, so this can ship as a patch release.

Split out of #452 so the fixes are not blocked behind that PR's breaking Swift 6 changes. #452 keeps the same two commits and should be rebased once this merges.

Upstream / Metadata

• Google libphonenumber ref: unchanged (v9.0.38)
• Metadata updated: no
• Geocoding metadata updated: no — the metadata was always correct, it was never being read

The bugs

Metadata was never found under SwiftPM. NBGeocoderMetaDataHelper appended GeocodingMetaData.bundle to -[NSBundle bundleForClass:].resourceURL, which is where CocoaPods, Carthage, and manual integration put the databases. SwiftPM nests them inside a generated wrapper bundle. No database was opened, so every lookup fell through to countryNameForNumber: with no error and no crash:

let number = try PhoneNumberUtility.shared.parse("6502530000", defaultRegion: "US")
PhoneNumberGeocoder.shared.description(for: number, languageCode: "en")
// before: "United States"    after: "Mountain View, CA"

The database has carried 1650253 → Mountain View, CA all along.

191c758 fixed this class of bug for carrier and timezone metadata and recorded that geocoding resolves its bundle differently and was unaffected. It does resolve it differently, but it was affected. Only the Objective-C tests covered geocoding and they inject a test bundle, so the shipped path was never exercised — and the two Swift facade tests that did run had pinned "United States" as the expected value. Those assertions are corrected here.

A lookup for an uncovered country disabled that language permanently. Only en.db has worldwide coverage; the others carry their own country. Preparing the query against a missing table fails, and the failed statement was left in place, so every later lookup in that language short-circuited on a NULL statement. A Korean-locale app that geocoded one US number lost city-level Korean geocoding for the rest of the process. The regression test for this fails before the fix and passes after it, verified by reverting the fix in place.

The first commit is a prerequisite: the geocoder's per-language helper cache was a check-then-insert, so concurrent callers could each open their own SQLite connection for the same language. It also locks NBMetadataHelper's lazily built region table, which had no synchronization at all, and narrows the regular-expression cache's lock so compilation happens outside it.

Compatibility

No API changes. Two behavioral changes worth calling out in release notes:

• SwiftPM consumers of libPhoneNumberGeocoding start receiving locality descriptions where they previously received country names. Apps that display the result directly will show different text.
• CocoaPods, Carthage, and manual integrations are unaffected by the bundle fix; they already resolved the databases.

Parity Checks

• swift scripts/checkUpstreamTestParity.swift — no gaps
• swift scripts/checkVersionConsistency.swift

Tests

• swift test — 231 XCTest + 7 Swift Testing, 0 failures
• LC_ALL=ko_KR.UTF-8 LANG=ko_KR.UTF-8 swift test
• swift build -c release
• xcodebuild test -scheme libPhoneNumber — TEST SUCCEEDED
• xcodebuild test -scheme libPhoneNumberGeocoding — TEST SUCCEEDED
• git diff --check

Notes

• The new PhoneNumberGeocodingFacadeTests suite covers localization, the user-region split, the uncovered-country regression, and concurrent lookups through the shared geocoder.
• NBGeocoderMetaDataHelper.defaultMetadataBundle is exposed so integrators can check whether the metadata resolved at all, rather than silently receiving country-level results.
• No CHANGELOG.md entry: that file is introduced by Fix geocoding metadata resolution and adopt Swift 6 concurrency #452. If this ships first as a patch, the entries for these fixes should move under a released heading when Fix geocoding metadata resolution and adopt Swift 6 concurrency #452 is rebased.

🤖 Generated with Claude Code