@mailwoman/codex 9.0.0 → 9.2.0

package/README.md

@@ -41,7 +41,7 @@ import { lookupStreetSuffix } from "@mailwoman/codex/us"
 | **`fr`** | La Poste postcode format, CEDEX conventions, département codes                       |
 | **`gb`** | Royal Mail postcode format, post town conventions                                    |
 | **`de`** | Deutsche Post postcode format, Bundesland abbreviations                              |
-| **`ca`** | Canada Post postcode format, province abbreviations                                  |
+| **`ca`** | Canada Post postcode format, province abbreviations, the urban/rural FSA split       |
 | **`au`** | Australia Post postcode format, state abbreviations                                  |
 
 ## Cross-system utilities
@@ -49,15 +49,57 @@ import { lookupStreetSuffix } from "@mailwoman/codex/us"
 ```ts
 import { candidateSystemsForPostcode } from "@mailwoman/codex"
 
-// Which systems could "94043" belong to?
-candidateSystemsForPostcode("94043") // → ["us"]
-candidateSystemsForPostcode("75008") // → ["fr"]
-candidateSystemsForPostcode("10115") // → ["de"]
+// Which systems could this shape belong to? A five-digit run is not evidence of one country.
+candidateSystemsForPostcode("94043") // → ["us", "de", "fr"]
+candidateSystemsForPostcode("SW1A 1AA") // → ["gb"]
 
 // Address system conventions (forbidden tags, expected shapes, etc.)
 import { ADDRESS_SYSTEM_CONVENTIONS, conventionsForSystem } from "@mailwoman/codex"
 ```
 
+Note the first answer. This is a **shape** test, not a gazetteer membership test, and
+returning all three is the correct answer rather than a hedge — the caller's country
+scope is what narrows it. Picking one locale here would be a guess wearing a fact's
+clothes.
+
+## Postcode granularity: three tiers, each earned by measurement
+
+One `postalcode` placetype covers systems that are not comparable. An Irish Eircode
+names a single address; an Australian postcode names a locality. Between them sit
+most of the world, and the distinction that actually changes an answer is narrower:
+**is this code finer than the locality that contains it?**
+
+That is a fact about a country's _administrative_ geography, not its postal system,
+and code length does not predict it. France and Germany are both five digits and land
+on opposite sides.
+
+```ts
+import { isUnitGradePostcodeHit, areaPostcodeLeadsLocality } from "@mailwoman/codex"
+
+isUnitGradePostcodeHit("N7 0BT", "n70bt") // → true  (GB unit, and the resolver hit the FULL code)
+isUnitGradePostcodeHit("N7 0BT", "n7") // → false (the resolver answered with the outward district)
+areaPostcodeLeadsLocality("DE") // → true  (a Gemeinde can be the size of Berlin)
+areaPostcodeLeadsLocality("FR") // → false (one code postal often spans several communes)
+```
+
+| Tier                                                                              | Members                           | What earned it                                                            |
+| --------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------- |
+| **unit-grade** (`UNIT_GRADE_POSTCODE`)                                            | NL PC6, GB unit, CA **urban** LDU | measured against rooftop truth — GB 38 m median, CA urban 78 m            |
+| **area, but still finer than the locality** (`AREA_POSTCODE_FINER_THAN_LOCALITY`) | DE                                | full-panel measurement: 5.84 km → 1.24 km p50, better on every percentile |
+| **area** (the default)                                                            | everything else                   | the locality-first convention                                             |
+
+Membership is earned by a measurement, never by a shape that looks tight. Canada is
+the case that shows why: its urban LDU is unit-grade, its **rural** LDU measures
+2.08 km against the locality's 929 m and is excluded — and Canada Post already marks
+the difference with a `0` in the second character, so the code says which before any
+lookup runs. The pooled Canadian number reads 0.10 km and looks like a uniform win;
+it is two populations, and a tier claim that averages two granularities is exactly
+what these tables exist to prevent.
+
+`@mailwoman/resolver`'s `admin-winner` consumes both predicates, and so does the
+browser demo's pin ranking — one definition, because the two once disagreed and
+nothing noticed.
+
 ## Design
 
 - **Zero runtime dependencies.** Pure TypeScript data tables — no database, no I/O,
@@ -92,6 +134,7 @@ questions, different tables.
 
 - [`@mailwoman/core`](../core) — `ComponentTag` schema, pipeline infrastructure
 - [`@mailwoman/address-id`](../address-id) — uses codex for stable address primary keys
+- [`@mailwoman/resolver`](../resolver) — consumes the granularity tiers to order a resolved tree
 - [Address system conventions](https://github.com/sister-software/mailwoman/blob/main/docs/engineering/reference/SCHEMA.mdx)
 
 ## License

package/ca/index.ts

@@ -4,7 +4,7 @@
  * @author Teffen Ellis, et al.
  *
  *   The Canadian address system (Canada Post / ISO 3166-2:CA): bilingual street types, alphanumeric
- *   postal codes, and the provinces and territories.
+ *   postcodes, and the provinces and territories.
  */
 
 export * from "./postal-code.ts"

package/ca/postal-code.ts

@@ -3,7 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Canadian postal codes: the branded type, the shape, normalization, and the FSA-letter →
+ *   Canadian postcodes: the branded type, the shape, normalization, and the FSA-letter →
  *   province/territory prior — the only ALPHANUMERIC postcode of the systems the codex models.
  *
  *   The informative contrast across `us/zipcode.ts`, `de/postleitzahl.ts`, `fr/code-postal.ts`, and
@@ -12,7 +12,7 @@
  *   - A US ZIP is numeric; its first digit maps to a loose BAND of states.
  *   - A German PLZ is numeric; its first digit maps to a Leitzone that CROSSES Bundesland borders.
  *   - A French code postal is numeric; its first TWO digits ARE the département.
- *   - A Canadian postal code is `A1A 1A1` — Letter Digit Letter, then Digit Letter Digit — and its
+ *   - A Canadian postcode is `A1A 1A1` — Letter Digit Letter, then Digit Letter Digit — and its
  *       first LETTER pins the province or territory directly (`M` → Ontario, `H` → Quebec, `V` →
  *       British Columbia). So like the French prefix it is a clean admin prior, but it does the job
  *       with a single ALPHA character rather than digits.
@@ -30,18 +30,18 @@ import type { Tagged } from "type-fest"
 import type { CanadianProvinceCode } from "./province.ts"
 
 /**
- * Characters in a Canadian postal code once spaces are stripped: `A1A1A1`.
+ * Characters in a Canadian postcode once spaces are stripped: `A1A1A1`.
  */
 const POSTAL_CODE_LENGTH = 6
 
 /**
- * A Canadian postal code: `A1A 1A1`. Six alphanumeric characters in a strict Letter-Digit-Letter-Digit-Letter-Digit
+ * A Canadian postcode: `A1A 1A1`. Six alphanumeric characters in a strict Letter-Digit-Letter-Digit-Letter-Digit
  * pattern, conventionally written with a single space after the third. Unlike the other systems' bare five digits, the
  * shape alone already says "Canada".
  *
  * @category Postal
  * @type string
- * @title Postal Code
+ * @title Postcode
  * @pattern ^[ABCEGHJ-NPRSTVXY]\d[ABCEGHJ-NPRSTV-Z] ?\d[ABCEGHJ-NPRSTV-Z]\d$
  */
 export type PostalCode = Tagged<string, "CaPostalCode">
@@ -56,7 +56,7 @@ export const CA_POSTAL_CODE_PATTERN = /^[ABCEGHJ-NPRSTVXY]\d[ABCEGHJ-NPRSTV-Z] ?
 /**
  * Normalize a postal-code surface form to canonical `A1A 1A1`: uppercase and ensure exactly one space between the FSA
  * (first three chars) and the LDU (last three) — `K1A0B1` → `K1A 0B1`, `k1a 0b1` → `K1A 0B1`. Returns null if the input
- * is not a valid Canadian postal code.
+ * is not a valid Canadian postcode.
  */
 export function normalizeCaPostalCode(raw: unknown): PostalCode | null {
 	if (typeof raw !== "string") return null
@@ -69,7 +69,7 @@ export function normalizeCaPostalCode(raw: unknown): PostalCode | null {
 }
 
 /**
- * Type-predicate for a Canadian postal code (accepts the spaced or unspaced surface form).
+ * Type-predicate for a Canadian postcode (accepts the spaced or unspaced surface form).
  */
 export function isCaPostalCode(input: unknown): input is PostalCode {
 	return typeof input === "string" && CA_POSTAL_CODE_PATTERN.test(input)
@@ -102,9 +102,9 @@ export const FSA_LETTER_TO_PROVINCE: Record<string, CanadianProvinceCode | Canad
 }
 
 /**
- * The province/territory a postal code belongs to, via its FSA first letter. Returns the single code for the clean
- * letters, the `["NT", "NU"]` pair for the shared `X`, and null if the input is not a valid Canadian postal code (or
- * its first letter has no province, which the pattern already forbids).
+ * The province/territory a postcode belongs to, via its FSA first letter. Returns the single code for the clean
+ * letters, the `["NT", "NU"]` pair for the shared `X`, and null if the input is not a valid Canadian postcode (or its
+ * first letter has no province, which the pattern already forbids).
  */
 export function provinceOfPostalCode(postalCode: unknown): CanadianProvinceCode | CanadianProvinceCode[] | null {
 	const normalized = normalizeCaPostalCode(postalCode)
@@ -115,7 +115,7 @@ export function provinceOfPostalCode(postalCode: unknown): CanadianProvinceCode
 }
 
 /**
- * True when a postal code is RURAL: its SECOND character (the FSA's first digit) is `0`. Canada Post uses a `0` in that
+ * True when a postcode is RURAL: its SECOND character (the FSA's first digit) is `0`. Canada Post uses a `0` in that
  * position to mark the lower-density delivery zones (rural routes, small communities) — the contrast with the urban
  * `1`–`9` FSAs. Returns false for a non-code.
  */

package/country/display-names.ts

@@ -0,0 +1,150 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Country surface forms across scripts, enumerated from the RUNTIME's own ICU via `Intl.DisplayNames`.
+ *
+ *   The gazetteer holds country names in English and little else, which is why a bare `格鲁吉亚` (Georgia the country,
+ *   Chinese), `沙特阿拉伯` or `巴布亚新几内亚` resolves to nothing while `佐治亚州` (Georgia the US state) resolves
+ *   correctly — the state is a real WOF record carrying multilingual names, and 140 of the 237 country rows are
+ *   synthetic and carry only a canonical English name. Measured 2026-08-15; WOF has no Chinese country names at all,
+ *   and `geonames-aliases.ts` filters every alias through a Latin-script regex.
+ *
+ *   ICU already knows all of it. No download, no vendored corpus, no licence question, and no drift against a snapshot
+ *   we would otherwise have to refresh: the names come from the same ICU the runtime uses for every other
+ *   locale-sensitive operation. Measured coverage at time of writing: **280 regions, 5,244 distinct surfaces** across
+ *   the locale × style grid below.
+ *
+ *   This module ENUMERATES. It does not decide what the gazetteer stores — see the candidate build for that, and note
+ *   that a surface here is a NAME THE WORLD USES, never an authority's designation.
+ */
+
+/**
+ * The locales whose display names are enumerated. Chosen for script coverage rather than speaker count: each entry
+ * either contributes a distinct script (Han simplified/traditional, Kana, Hangul, Arabic, Cyrillic, Devanagari, Hebrew,
+ * Greek, Thai) or a major Latin-script exonym set that diverges from English.
+ *
+ * Adding a locale is additive and safe — surfaces are deduplicated — but every addition grows the candidate table, so
+ * it earns its place by contributing surfaces a user would plausibly type.
+ */
+export const DISPLAY_NAME_LOCALES = [
+	"en",
+	"zh-Hans",
+	"zh-Hant",
+	"ja",
+	"ko",
+	"ar",
+	"ru",
+	"es",
+	"fr",
+	"de",
+	"hi",
+	"pt",
+	"it",
+	"nl",
+	"pl",
+	"tr",
+	"vi",
+	"th",
+	"id",
+	"fa",
+	"he",
+	"uk",
+	"sv",
+	"el",
+] as const
+
+/**
+ * `long` is the ordinary name, `short` supplies the abbreviations people actually type (`UK`, `US`, `アメリカ`), and
+ * `narrow` occasionally differs again. All three are enumerated because the query register is whatever the user wrote.
+ */
+export const DISPLAY_NAME_STYLES = ["long", "short", "narrow"] as const
+
+/**
+ * One country surface and where it came from.
+ */
+export interface CountryDisplayName {
+	/**
+	 * ISO 3166-1 alpha-2.
+	 */
+	iso2: string
+	/**
+	 * The surface as ICU renders it, unmodified — normalisation is the consumer's job, and the raw form is what a
+	 * provenance record needs to be auditable.
+	 */
+	name: string
+	/**
+	 * BCP-47 tag this surface came from. Carried so a consumer can scope by locale rather than accepting every script for
+	 * every query.
+	 */
+	locale: string
+}
+
+/**
+ * Two-letter sequences that are not ISO 3166-1 regions. `Intl.DisplayNames.of` echoes its input for an unknown code, so
+ * the echo IS the miss signal — no separate region list to keep in sync.
+ */
+/**
+ * The AA–ZZ sweep bounds. ISO 3166-1 alpha-2 is exactly two uppercase ASCII letters, so enumerating the whole square
+ * and keeping what ICU recognises avoids carrying a region list that would need its own upkeep.
+ */
+const ASCII_A = 65
+const ASCII_Z = 90
+
+function isEcho(code: string, rendered: string | undefined): boolean {
+	return !rendered || rendered === code
+}
+
+/**
+ * Enumerate every AA–ZZ code against the locale × style grid, keeping what ICU recognises.
+ *
+ * Deduplicated per (iso2, name): the same surface reached from several locales is one row, and the FIRST locale that
+ * produced it wins the attribution — deterministic because {@link DISPLAY_NAME_LOCALES} is ordered.
+ */
+export function* enumerateCountryDisplayNames(
+	locales: readonly string[] = DISPLAY_NAME_LOCALES
+): Generator<CountryDisplayName> {
+	const formatters = locales.flatMap((locale) =>
+		DISPLAY_NAME_STYLES.map((style) => {
+			try {
+				return { locale, formatter: new Intl.DisplayNames([locale], { type: "region", style }) }
+			} catch {
+				// A runtime without this locale's data degrades to fewer surfaces, never to an error.
+				return undefined
+			}
+		}).filter((f) => f !== null && f !== undefined)
+	)
+
+	for (let a = ASCII_A; a <= ASCII_Z; a++) {
+		for (let b = ASCII_A; b <= ASCII_Z; b++) {
+			const iso2 = String.fromCharCode(a, b)
+			const seen = new Set<string>()
+
+			for (const { locale, formatter } of formatters) {
+				let rendered: string | undefined
+
+				try {
+					rendered = formatter.of(iso2)
+				} catch {
+					continue
+				}
+
+				if (isEcho(iso2, rendered) || seen.has(rendered!)) continue
+				seen.add(rendered!)
+
+				yield { iso2, name: rendered!, locale }
+			}
+		}
+	}
+}
+
+/**
+ * Every surface ICU knows for one country. Convenience over {@link enumerateCountryDisplayNames} for a single lookup;
+ * the generator is the bulk path.
+ */
+export function countryDisplayNames(iso2: string, locales?: readonly string[]): string[] {
+	const upper = iso2.toUpperCase()
+
+	return [...enumerateCountryDisplayNames(locales)].filter((n) => n.iso2 === upper).map((n) => n.name)
+}

package/country/index.ts

@@ -8,8 +8,10 @@
 
 export * from "./codes.ts"
 export * from "./country.ts"
+export * from "./display-names.ts"
 export * from "./names.ts"
 export * from "./official-languages.ts"
+export * from "./population.ts"
 export * from "./reference-data.ts"
 export * from "./reference.ts"
 export * from "./subdivision.ts"

package/country/population.ts

@@ -0,0 +1,265 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   GENERATED — do not edit by hand. Per-country population, derived from GeoNames countryInfo.txt
+ *   (https://download.geonames.org/export/dump/countryInfo.txt, CC-BY-4.0). Estimates are
+ *   census-vintage; a prominence race reads the magnitude, not the currency. Countries GeoNames
+ *   declines to estimate are ABSENT, never zero.
+ *   Regenerate with: mailwoman dev generate country-population
+ */
+
+/**
+ * ISO 3166-1 alpha-2 → population estimate.
+ */
+export const COUNTRY_POPULATION: Readonly<Record<string, number>> = {
+	AD: 77_006,
+	AE: 9_630_959,
+	AF: 37_172_386,
+	AG: 96_286,
+	AI: 13_254,
+	AL: 2_866_376,
+	AM: 3_090_500,
+	AN: 300_000,
+	AO: 30_809_762,
+	AR: 44_494_502,
+	AS: 55_465,
+	AT: 8_847_037,
+	AU: 24_992_369,
+	AW: 105_845,
+	AX: 26_711,
+	AZ: 10_224_900,
+	BA: 3_323_929,
+	BB: 286_641,
+	BD: 161_356_039,
+	BE: 11_422_068,
+	BF: 19_751_535,
+	BG: 7_000_039,
+	BH: 1_569_439,
+	BI: 11_175_378,
+	BJ: 11_485_048,
+	BL: 8450,
+	BM: 63_968,
+	BN: 428_962,
+	BO: 11_353_142,
+	BQ: 18_012,
+	BR: 209_469_333,
+	BS: 385_640,
+	BT: 754_394,
+	BW: 2_254_126,
+	BY: 9_485_386,
+	BZ: 383_071,
+	CA: 37_058_856,
+	CC: 628,
+	CD: 84_068_091,
+	CF: 4_666_377,
+	CG: 5_244_363,
+	CH: 8_516_543,
+	CI: 25_069_229,
+	CK: 21_388,
+	CL: 18_729_160,
+	CM: 25_216_237,
+	CN: 1_411_778_724,
+	CO: 49_648_685,
+	CR: 4_999_441,
+	CS: 10_829_175,
+	CU: 11_338_138,
+	CV: 543_767,
+	CW: 159_849,
+	CX: 1500,
+	CY: 1_189_265,
+	CZ: 10_625_695,
+	DE: 82_927_922,
+	DJ: 958_920,
+	DK: 5_797_446,
+	DM: 71_625,
+	DO: 10_627_165,
+	DZ: 42_228_429,
+	EC: 17_084_357,
+	EE: 1_320_884,
+	EG: 98_423_595,
+	EH: 273_008,
+	ER: 6_209_262,
+	ES: 46_723_749,
+	ET: 109_224_559,
+	FI: 5_518_050,
+	FJ: 883_483,
+	FK: 2638,
+	FM: 112_640,
+	FO: 48_497,
+	FR: 66_987_244,
+	GA: 2_119_275,
+	GB: 66_488_991,
+	GD: 111_454,
+	GE: 3_704_500,
+	GF: 195_506,
+	GG: 65_228,
+	GH: 29_767_108,
+	GI: 33_718,
+	GL: 56_025,
+	GM: 2_280_102,
+	GN: 12_414_318,
+	GP: 443_000,
+	GQ: 1_308_974,
+	GR: 10_727_668,
+	GS: 30,
+	GT: 17_247_807,
+	GU: 165_768,
+	GW: 1_874_309,
+	GY: 779_004,
+	HK: 7_396_076,
+	HN: 9_587_522,
+	HR: 3_871_833,
+	HT: 11_123_176,
+	HU: 9_768_785,
+	ID: 267_663_435,
+	IE: 4_853_506,
+	IL: 8_883_800,
+	IM: 84_077,
+	IN: 1_352_617_328,
+	IO: 4000,
+	IQ: 38_433_600,
+	IR: 81_800_269,
+	IS: 353_574,
+	IT: 60_431_283,
+	JE: 90_812,
+	JM: 2_934_855,
+	JO: 9_956_011,
+	JP: 126_529_100,
+	KE: 51_393_010,
+	KG: 6_315_800,
+	KH: 16_249_798,
+	KI: 115_847,
+	KM: 832_322,
+	KN: 52_441,
+	KP: 25_549_819,
+	KR: 51_635_256,
+	KW: 4_137_309,
+	KY: 64_174,
+	KZ: 18_276_499,
+	LA: 7_061_507,
+	LB: 6_848_925,
+	LC: 181_889,
+	LI: 37_910,
+	LK: 21_670_000,
+	LR: 4_818_977,
+	LS: 2_108_132,
+	LT: 2_789_533,
+	LU: 607_728,
+	LV: 1_926_542,
+	LY: 6_678_567,
+	MA: 36_029_138,
+	MC: 38_682,
+	MD: 3_545_883,
+	ME: 622_345,
+	MF: 37_264,
+	MG: 26_262_368,
+	MH: 58_413,
+	MK: 2_082_958,
+	ML: 19_077_690,
+	MM: 53_708_395,
+	MN: 3_170_208,
+	MO: 631_636,
+	MP: 56_882,
+	MQ: 432_900,
+	MR: 4_403_319,
+	MS: 9341,
+	MT: 483_530,
+	MU: 1_265_303,
+	MV: 515_696,
+	MW: 17_563_749,
+	MX: 126_190_788,
+	MY: 31_528_585,
+	MZ: 29_495_962,
+	NA: 2_448_255,
+	NC: 284_060,
+	NE: 22_442_948,
+	NF: 1828,
+	NG: 195_874_740,
+	NI: 6_465_513,
+	NL: 17_231_017,
+	NO: 5_314_336,
+	NP: 28_087_871,
+	NR: 12_704,
+	NU: 2166,
+	NZ: 4_885_500,
+	OM: 4_829_483,
+	PA: 4_176_873,
+	PE: 31_989_256,
+	PF: 277_679,
+	PG: 8_606_316,
+	PH: 106_651_922,
+	PK: 212_215_030,
+	PL: 37_978_548,
+	PM: 7012,
+	PN: 46,
+	PR: 3_195_153,
+	PS: 4_569_087,
+	PT: 10_281_762,
+	PW: 17_907,
+	PY: 6_956_071,
+	QA: 2_781_677,
+	RE: 776_948,
+	RO: 19_473_936,
+	RS: 6_982_084,
+	RU: 144_478_050,
+	RW: 12_301_939,
+	SA: 33_699_947,
+	SB: 652_858,
+	SC: 96_762,
+	SD: 41_801_533,
+	SE: 10_183_175,
+	SG: 5_638_676,
+	SH: 7460,
+	SI: 2_067_372,
+	SJ: 2550,
+	SK: 5_447_011,
+	SL: 7_650_154,
+	SM: 33_785,
+	SN: 15_854_360,
+	SO: 15_008_154,
+	SR: 575_991,
+	SS: 8_260_490,
+	ST: 197_700,
+	SV: 6_420_744,
+	SX: 40_654,
+	SY: 16_906_283,
+	SZ: 1_136_191,
+	TC: 37_665,
+	TD: 15_477_751,
+	TF: 140,
+	TG: 7_889_094,
+	TH: 69_428_524,
+	TJ: 9_100_837,
+	TK: 1466,
+	TL: 1_267_972,
+	TM: 5_850_908,
+	TN: 11_565_204,
+	TO: 103_197,
+	TR: 82_319_724,
+	TT: 1_389_858,
+	TV: 11_508,
+	TW: 23_451_837,
+	TZ: 56_318_348,
+	UA: 40_000_000,
+	UG: 42_723_139,
+	US: 327_167_434,
+	UY: 3_449_299,
+	UZ: 32_955_400,
+	VA: 921,
+	VC: 110_211,
+	VE: 28_870_195,
+	VG: 29_802,
+	VI: 106_977,
+	VN: 95_540_395,
+	VU: 292_680,
+	WF: 16_025,
+	WS: 196_130,
+	XK: 1_845_300,
+	YE: 28_498_687,
+	YT: 279_471,
+	ZA: 57_779_622,
+	ZM: 17_351_822,
+	ZW: 16_868_409,
+}

package/country/subdivision.ts

@@ -26,6 +26,7 @@
  *   re-keys those two existing tables into one subdivision→country view.
  */
 
+import { AU_STATE_ABBREVIATIONS } from "../au/state.ts"
 import { CA_PROVINCES } from "../ca/province.ts"
 import { foldName } from "../normalize.ts"
 import { US_STATE_BY_ABBREVIATION } from "../us/state.ts"
@@ -91,3 +92,61 @@ export function matchSubdivision(token: string | null | undefined): SubdivisionM
 
 	return SUBDIVISION_LOOKUP.get(foldName(token)) ?? null
 }
+
+/**
+ * Per-country subdivision lookups for callers that already KNOW the country. Kept separate from
+ * {@link SUBDIVISION_LOOKUP} on purpose: the combined map is only unambiguous because the US and CA sets are disjoint,
+ * and Australia breaks that property twice — `WA` collides with Washington and `NT` with the Northwest Territories. A
+ * country-scoped caller (the admin-coherence check reads the winner's resolver-stamped country) dissolves the collision
+ * instead of arbitrating it.
+ */
+const SCOPED_SUBDIVISION_LOOKUP: ReadonlyMap<string, ReadonlyMap<string, SubdivisionMatch>> = (() => {
+	const byCountry = new Map<string, Map<string, SubdivisionMatch>>()
+
+	const put = (country: string, key: string, match: SubdivisionMatch): void => {
+		const folded = foldName(key)
+
+		if (!folded.length) return
+
+		const scoped = byCountry.get(country) ?? new Map<string, SubdivisionMatch>()
+
+		byCountry.set(country, scoped)
+
+		if (!scoped.has(folded)) {
+			scoped.set(folded, match)
+		}
+	}
+
+	for (const [code, name] of Object.entries(US_STATE_BY_ABBREVIATION)) {
+		const match: SubdivisionMatch = { code, name, country: "US" }
+		put("US", code, match)
+		put("US", name, match)
+	}
+
+	for (const info of Object.values(CA_PROVINCES)) {
+		const match: SubdivisionMatch = { code: info.code, name: info.name, country: "CA" }
+		put("CA", info.code, match)
+		put("CA", info.name, match)
+		put("CA", info.french, match)
+	}
+
+	for (const [code, name] of Object.entries(AU_STATE_ABBREVIATIONS)) {
+		const match: SubdivisionMatch = { code, name, country: "AU" }
+		put("AU", code, match)
+		put("AU", name, match)
+	}
+
+	return byCountry
+})()
+
+/**
+ * Resolve a subdivision surface form WITHIN one country. Same folding and return shape as {@link matchSubdivision}, but
+ * scoped: `WA` under `AU` is Western Australia, under `US` Washington, and under any other country null. Use this
+ * whenever the country is already established; the unscoped lookup exists for the address-line case where the
+ * subdivision itself is the country evidence.
+ */
+export function matchSubdivisionIn(countryAlpha2: string, token: string | null | undefined): SubdivisionMatch | null {
+	if (!token || typeof token !== "string") return null
+
+	return SCOPED_SUBDIVISION_LOOKUP.get(countryAlpha2.toUpperCase())?.get(foldName(token)) ?? null
+}

package/de/index.ts

@@ -3,7 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The German address system (Deutsche Post / ISO 3166-2:DE): street types, postal codes
+ *   The German address system (Deutsche Post / ISO 3166-2:DE): street types, postcodes
  *   (Postleitzahl), and the federal states (Bundesländer).
  */