@mailwoman/codex 9.1.0 → 9.3.0

package/README.md

@@ -23,7 +23,7 @@ fr.postcodePattern // → /^\d{5}$/
 
 // US ZIP code branded type
 import { us } from "@mailwoman/codex"
-const zip: us.ZipCode = "94043" // branded, not just string
+const zip: us.ZipCode = "94043" // branded, not string alone
 ```
 
 ## Supported address systems
@@ -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,22 +49,64 @@ 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 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,
   no network. Suitable for bundling into browser and edge environments.
 - **Branded types.** ZIP codes, postcodes, and abbreviations carry nominal types
   so the type system catches locale mismatches at compile time.
-- **Single source of truth.** The resolver, the decoder's convention masks, the
+- **One definition.** The resolver, the decoder's convention masks, the
   corpus synthesis layer, and the matcher all import from `@mailwoman/codex`.
 
 ## The normative tier (codex vs the libpostal dictionaries)
@@ -78,7 +120,7 @@ be merged:
   invariance transforms, and formatting (rendering `N` vs `North` requires knowing
   which form the authority prints).
 - **The libpostal dictionaries** (`core/data/libpostal/dictionaries/`, Pelias
-  lineage) **are descriptive**: everything people actually write, including forms no
+  lineage) **are descriptive**: everything people write, including forms no
   authority recognizes (`en/directionals.txt` lists `lower`/`upper`/`central`).
   Their consumers are recall-shaped — evidence-lexicon curation laws, street
   decomposition for training gold, the street-morphology FST. See the README in
@@ -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/{address-system-conventions.ts → lib/address-system-conventions.ts}

@@ -18,9 +18,9 @@
  *   by the caller) — an undetected system parses exactly as before.
  */
 
-import { CODE_POSTAL_PATTERN } from "./fr/code-postal.ts"
-import { UK_POSTCODE_PATTERN } from "./gb/postcode.ts"
-import type { SystemCode } from "./postcode-systems.ts"
+import { CODE_POSTAL_PATTERN } from "#fr/code-postal"
+import { UK_POSTCODE_PATTERN } from "#gb/postcode"
+import type { SystemCode } from "#postcode-systems"
 
 export interface AddressSystemConventions {
 	/**
@@ -48,11 +48,11 @@ export const ADDRESS_SYSTEM_CONVENTIONS: Partial<Record<SystemCode, AddressSyste
 	 * street-suffix class; Pub-28's suffix decomposition has no French counterpart).
 	 *
 	 * Provenance / why this is NOT a blanket prefix+suffix forbid (#719, 2026-06-18): an earlier model mis-tagged the
-	 * leading "Rue" as a US-style `street_suffix` (RUE is a Pub-28 suffix variant) — the 2026-06-10 v1.1.0 gate — so #511
-	 * forbade BOTH affix tags to stop that leakage. That forbid was correct for THAT model but became a live production
-	 * bug for the current one: the shipped model (v1.5.0) emits the FR `street_prefix` correctly, but the conventions
-	 * mask was a hard −1e9 on every B-/I-street_prefix emission, so the detected-FR parse could never KEEP a prefix — it
-	 * destroyed `street_prefix` wholesale (measured on data/eval/external/ fr-street-prefix-real.jsonl at
+	 * leading "Rue" as a US-style `street_suffix` (RUE is a Pub-28 suffix variant) — the 2026-06-10 v1.1.0 promotion eval
+	 * — so #511 forbade BOTH affix tags to stop that leakage. That forbid was correct for THAT model but became a live
+	 * production bug for the current one: the shipped model (v1.5.0) emits the FR `street_prefix` correctly, but the
+	 * conventions mask was a hard −1e9 on every B-/I-street_prefix emission, so the detected-FR parse could never KEEP a
+	 * prefix — it destroyed `street_prefix` wholesale (measured on data/eval/external/ fr-street-prefix-real.jsonl at
 	 * conventions=auto: F1 0.0 with the forbid on → 80.0 with it off; the larger real-FR eval reported the same collapse,
 	 * ~96 → ~0.6). We keep ONLY `street_suffix` forbidden: the current model with the forbid OFF shows zero FR
 	 * street_suffix leakage (fp=0 on that same slice) and FR has no trailing street suffix, so the constraint costs
@@ -72,7 +72,7 @@ export const ADDRESS_SYSTEM_CONVENTIONS: Partial<Record<SystemCode, AddressSyste
 	 * the raw text — exactly the shape-INVALID class `postcodePattern` exists to flag.
 	 *
 	 * Provenance (#1275, 2026-07-24): on the GB golden board's 106 postcode rows under the en-gb bundle, the clip class
-	 * (parsed postcode = proper suffix of the truth) was 44/106 with this row absent — the repair gate never opened
+	 * (parsed postcode = proper suffix of the truth) was 44/106 with this row absent — the repair check never opened
 	 * because `conventionsForSystem("gb")` returned null. With the repair reachable, exact 26 → 83 and the clip class
 	 * goes to zero. No `forbiddenTags`: no measured GB-ungrammatical tag class exists (the FR street_suffix forbid's
 	 * lesson — a forbid needs measured zero-cost receipts, and GB street grammar shares the trailing-suffix family with

package/{au → lib/au}/index.ts

@@ -9,7 +9,7 @@
  *   territories, and the 4-digit postcode.
  */
 
-export * from "./delivery-service.ts"
-export * from "./level-designator.ts"
-export * from "./postcode.ts"
-export * from "./state.ts"
+export * from "#au/delivery-service"
+export * from "#au/level-designator"
+export * from "#au/postcode"
+export * from "#au/state"

package/{ca → lib/ca}/index.ts

@@ -4,9 +4,9 @@
  * @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"
-export * from "./province.ts"
-export * from "./street-type.ts"
+export * from "#ca/postal-code"
+export * from "#ca/province"
+export * from "#ca/street-type"

package/{ca → lib/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.
@@ -27,21 +27,21 @@
 
 import type { Tagged } from "type-fest"
 
-import type { CanadianProvinceCode } from "./province.ts"
+import type { CanadianProvinceCode } from "#ca/province"
 
 /**
- * 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/{ca → lib/ca}/province.ts

@@ -16,7 +16,7 @@
  *   regions, the Canadian code IS a surface form, not just a resolver key.
  */
 
-import { foldName } from "../normalize.ts"
+import { foldName } from "#normalize"
 
 /**
  * Per-province record: ISO 3166-2:CA code, English name, and the co-official French name.

package/{ca → lib/ca}/street-type.ts

@@ -23,6 +23,8 @@
  *   Ouest = West is recognized.
  */
 
+import { foldToken } from "#normalize"
+
 /**
  * English Canadian street-type words (Canada Post's recognized set, lowercase). Appear as the TRAILING token of an
  * English street name (`Maple Avenue`, `Sunset Crescent`).
@@ -53,7 +55,7 @@ export const CA_STREET_TYPES_EN: ReadonlySet<string> = new Set([
 	"green",
 	"bay",
 	"cove",
-	"gate",
+	"check",
 	"point",
 	"ridge",
 	"view",
@@ -86,14 +88,10 @@ export const CA_STREET_TYPES_FR: ReadonlySet<string> = new Set([
 ])
 
 /**
- * Strip diacritics + lowercase so `Côte`/`cote`, `Allée`/`allee`, `Crescent`/`crescent` key alike.
+ * {@link foldToken}, letters only, so `Côte`/`cote`, `Allée`/`allee`, `Crescent`/`crescent` key alike.
  */
-function foldToken(s: string): string {
-	return s
-		.toLowerCase()
-		.normalize("NFD")
-		.replaceAll(/[\u0300-\u036F]/g, "")
-		.replaceAll(/[^a-z]/g, "")
+function foldLetters(s: string): string {
+	return foldToken(s).replaceAll(/[^a-z]/g, "")
 }
 
 /**
@@ -103,11 +101,11 @@ const STREET_WORD_SET: ReadonlySet<string> = (() => {
 	const out = new Set<string>()
 
 	for (const w of CA_STREET_TYPES_EN) {
-		out.add(foldToken(w))
+		out.add(foldLetters(w))
 	}
 
 	for (const w of CA_STREET_TYPES_FR) {
-		out.add(foldToken(w))
+		out.add(foldLetters(w))
 	}
 
 	return out
@@ -120,7 +118,7 @@ const STREET_WORD_SET: ReadonlySet<string> = (() => {
  */
 export function isCanadianStreetWord(token: unknown): boolean {
 	if (typeof token !== "string") return false
-	const t = foldToken(token)
+	const t = foldLetters(token)
 
 	return t.length > 0 && STREET_WORD_SET.has(t)
 }
@@ -154,7 +152,7 @@ export const CA_DIRECTIONALS: Record<string, "N" | "S" | "E" | "W"> = {
  */
 export function isCanadianDirectional(token: unknown): boolean {
 	if (typeof token !== "string") return false
-	const t = foldToken(token)
+	const t = foldLetters(token)
 
 	if (!t.length) return false
 

package/{country → lib/country}/codes.ts

@@ -4,7 +4,7 @@
  * @author Teffen Ellis, et al.
  */
 
-import type { CountryName } from "./names.ts"
+import type { CountryName } from "#country/names"
 
 /**
  * @category Country

package/{country → lib/country}/country.ts

@@ -3,18 +3,19 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Country recognition for the `country` parity lever. The ISO 3166-1 base (names + alpha-2/alpha-3)
+ *   Country recognition for the `country` parity change. The ISO 3166-1 base (names + alpha-2/alpha-3)
  *   is salvaged from isp-nexus `spatial/countries` ({@link ./names.ts}, {@link ./codes.ts}); this
  *   adds the layer ISO doesn't carry — the **surface forms** addresses actually use (endonyms +
  *   common abbreviations: "USA"/"United States"/"U.S."; "Deutschland"/"Germany"; "España"/"Spain")
- *   — plus a {@link matchCountry} resolver the corpus country-shard + parsing reuse. Same shape as
+ *   — plus a {@link matchCountry} resolver the corpus country-extract + parsing reuse. Same shape as
  *   the other codex matchers (street-suffix, directional, po-box).
  */
 
-import { Alpha3ToCountryRecord, CountryISO2 } from "./codes.ts"
-import type { CountryName } from "./names.ts"
+import { Alpha3ToCountryRecord, CountryISO2 } from "#country/codes"
+import type { CountryName } from "#country/names"
+import { foldName } from "#normalize"
 
-export { Alpha3ToCountryRecord, CountryISO2, type CountryISO3 } from "./codes.ts"
+export { Alpha3ToCountryRecord, CountryISO2, type CountryISO3 } from "#country/codes"
 
 /**
  * Common real-address surface forms per ISO 3166-1 alpha-2, **canonical English name first** then endonym +
@@ -51,9 +52,11 @@ export const ISO2_TO_NAME: ReadonlyMap<string, CountryName> = new Map(
 )
 
 /**
- * Any recognized country surface form / canonical name / alpha-2 / alpha-3 → alpha-2 code. Built once at module load,
- * lowercase-keyed. Canonical names + codes from the ISO base, plus the curated surface forms (surface forms win on
- * collision — they're the address-facing spellings).
+ * Any recognized country surface form / canonical name / alpha-2 / alpha-3 → alpha-2 code. Built once at module load.
+ * Each surface contributes its lowercased key AND its {@link foldName}-folded key when the fold leaves anything — a
+ * non-Latin surface like `日本` survives only as its lowercased self — so accented and punctuated variants resolve.
+ * Canonical names + codes from the ISO base, plus the curated surface forms (surface forms win on collision — they're
+ * the address-facing spellings).
  */
 export const COUNTRY_LOOKUP: ReadonlyMap<string, string> = (() => {
 	const out = new Map<string, string>()
@@ -64,6 +67,12 @@ export const COUNTRY_LOOKUP: ReadonlyMap<string, string> = (() => {
 		if (key && !out.has(key)) {
 			out.set(key, iso2)
 		}
+
+		const folded = foldName(k)
+
+		if (folded && !out.has(folded)) {
+			out.set(folded, iso2)
+		}
 	}
 
 	// ISO base: canonical name + alpha-2 + alpha-3.
@@ -88,12 +97,32 @@ export const COUNTRY_LOOKUP: ReadonlyMap<string, string> = (() => {
 	for (const [iso2, forms] of Object.entries(COUNTRY_SURFACE_FORMS)) {
 		for (const f of forms) {
 			out.set(f.trim().toLowerCase(), iso2)
+
+			const folded = foldName(f)
+
+			if (folded) {
+				out.set(folded, iso2)
+			}
 		}
 	}
 
 	return out
 })()
 
+/**
+ * Probe the lookup the way it is keyed: the lowercased surface first, then the {@link foldName} fold when it is
+ * non-empty.
+ */
+function probeCountry(token: string): string | undefined {
+	const direct = COUNTRY_LOOKUP.get(token.trim().toLowerCase())
+
+	if (direct) return direct
+
+	const folded = foldName(token)
+
+	return folded ? COUNTRY_LOOKUP.get(folded) : undefined
+}
+
 /**
  * Result of a country match: the alpha-2 code, the canonical English name, and the matched surface.
  */
@@ -104,13 +133,13 @@ export interface CountryMatch {
 }
 
 /**
- * Resolve a token (surface form, canonical name, alpha-2, or alpha-3) to a country. Case-insensitive. Returns null if
- * unrecognized. Multi-word names ("United States", "Great Britain") must be passed as the whole phrase — the caller
- * decides the span; this matches it.
+ * Resolve a token (surface form, canonical name, alpha-2, or alpha-3) to a country. Case-, accent-, and
+ * punctuation-insensitive. Returns null if unrecognized. Multi-word names ("United States", "Great Britain") must be
+ * passed as the whole phrase — the caller decides the span; this matches it.
  */
 export function matchCountry(token: string | null | undefined): CountryMatch | null {
 	if (!token || typeof token !== "string") return null
-	const iso2 = COUNTRY_LOOKUP.get(token.trim().toLowerCase())
+	const iso2 = probeCountry(token)
 
 	if (!iso2) return null
 
@@ -121,11 +150,11 @@ export function matchCountry(token: string | null | undefined): CountryMatch | n
  * Case-insensitive check: is the token any recognized country form?
  */
 export function isCountryToken(token: unknown): boolean {
-	return typeof token === "string" && COUNTRY_LOOKUP.has(token.trim().toLowerCase())
+	return typeof token === "string" && probeCountry(token) !== undefined
 }
 
 /**
- * The preferred render forms for an alpha-2 (canonical first), for synth shards. Empty if none curated.
+ * The preferred render forms for an alpha-2 (canonical first), for synth extracts. Empty if none curated.
  */
 export function countrySurfaceForms(iso2: string): readonly string[] {
 	return (COUNTRY_SURFACE_FORMS as Record<string, readonly string[]>)[iso2.toUpperCase()] ?? []

package/lib/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/lib/country/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   ISO 3166-1 country reference + surface-form recognition (the `country` parity change).
+ */
+
+export * from "#country/codes"
+export * from "#country/country"
+export * from "#country/display-names"
+export * from "#country/names"
+export * from "#country/official-languages"
+export * from "#country/population"
+export * from "#country/reference-data"
+export * from "#country/reference"
+export * from "#country/subdivision"