@mailwoman/codex 9.0.0 → 9.2.0

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@mailwoman/codex",
-  "version": "9.0.0",
+  "version": "9.2.0",
   "description": "Per-address-system postal reference data + branded types (USPS street suffixes, US ZIP codes). Pure, zero-runtime-dep — the shared canonical home for postal-system primitives the parser, resolver, and synthesis layers all reach for.",
   "license": "AGPL-3.0-only OR LicenseRef-Commercial",
   "repository": {
     "type": "git",
     "url": "https://github.com/sister-software/mailwoman.git",
-    "directory": "codex"
+    "directory": "packages/codex"
   },
   "files": [
     "out/**/*.js",
@@ -20,7 +20,10 @@
     "!*.test.ts",
     "!*.test.tsx",
     "!**/*.test.ts",
-    "!**/*.test.tsx"
+    "!**/*.test.tsx",
+    "us/street-suffix.json",
+    "out/us/street-suffix.json",
+    "!test/**"
   ],
   "type": "module",
   "exports": {
@@ -76,6 +79,166 @@
     "./it": {
       "types": "./out/it/index.d.ts",
       "default": "./out/it/index.js"
+    },
+    "./address-system-conventions": {
+      "types": "./out/address-system-conventions.d.ts",
+      "default": "./out/address-system-conventions.js"
+    },
+    "./gb/postcode": {
+      "types": "./out/gb/postcode.d.ts",
+      "default": "./out/gb/postcode.js"
+    },
+    "./level-semantics": {
+      "types": "./out/level-semantics.d.ts",
+      "default": "./out/level-semantics.js"
+    },
+    "./postcode-systems": {
+      "types": "./out/postcode-systems.d.ts",
+      "default": "./out/postcode-systems.js"
+    },
+    "./au/delivery-service": {
+      "types": "./out/au/delivery-service.d.ts",
+      "default": "./out/au/delivery-service.js"
+    },
+    "./au/level-designator": {
+      "types": "./out/au/level-designator.d.ts",
+      "default": "./out/au/level-designator.js"
+    },
+    "./au/postcode": {
+      "types": "./out/au/postcode.d.ts",
+      "default": "./out/au/postcode.js"
+    },
+    "./au/state": {
+      "types": "./out/au/state.d.ts",
+      "default": "./out/au/state.js"
+    },
+    "./ca/postal-code": {
+      "types": "./out/ca/postal-code.d.ts",
+      "default": "./out/ca/postal-code.js"
+    },
+    "./ca/province": {
+      "types": "./out/ca/province.d.ts",
+      "default": "./out/ca/province.js"
+    },
+    "./ca/street-type": {
+      "types": "./out/ca/street-type.d.ts",
+      "default": "./out/ca/street-type.js"
+    },
+    "./country/country": {
+      "types": "./out/country/country.d.ts",
+      "default": "./out/country/country.js"
+    },
+    "./country/display-names": {
+      "types": "./out/country/display-names.d.ts",
+      "default": "./out/country/display-names.js"
+    },
+    "./country/official-languages": {
+      "types": "./out/country/official-languages.d.ts",
+      "default": "./out/country/official-languages.js"
+    },
+    "./country/reference": {
+      "types": "./out/country/reference.d.ts",
+      "default": "./out/country/reference.js"
+    },
+    "./country/subdivision": {
+      "types": "./out/country/subdivision.d.ts",
+      "default": "./out/country/subdivision.js"
+    },
+    "./de/bundesland": {
+      "types": "./out/de/bundesland.d.ts",
+      "default": "./out/de/bundesland.js"
+    },
+    "./de/postleitzahl": {
+      "types": "./out/de/postleitzahl.d.ts",
+      "default": "./out/de/postleitzahl.js"
+    },
+    "./de/street-type": {
+      "types": "./out/de/street-type.d.ts",
+      "default": "./out/de/street-type.js"
+    },
+    "./fr/cedex": {
+      "types": "./out/fr/cedex.d.ts",
+      "default": "./out/fr/cedex.js"
+    },
+    "./fr/code-postal": {
+      "types": "./out/fr/code-postal.d.ts",
+      "default": "./out/fr/code-postal.js"
+    },
+    "./fr/departement": {
+      "types": "./out/fr/departement.d.ts",
+      "default": "./out/fr/departement.js"
+    },
+    "./fr/region": {
+      "types": "./out/fr/region.d.ts",
+      "default": "./out/fr/region.js"
+    },
+    "./fr/voie": {
+      "types": "./out/fr/voie.d.ts",
+      "default": "./out/fr/voie.js"
+    },
+    "./gb/country": {
+      "types": "./out/gb/country.d.ts",
+      "default": "./out/gb/country.js"
+    },
+    "./gb/postcode-area": {
+      "types": "./out/gb/postcode-area.d.ts",
+      "default": "./out/gb/postcode-area.js"
+    },
+    "./gb/street-type": {
+      "types": "./out/gb/street-type.d.ts",
+      "default": "./out/gb/street-type.js"
+    },
+    "./jp/address-unit": {
+      "types": "./out/jp/address-unit.d.ts",
+      "default": "./out/jp/address-unit.js"
+    },
+    "./jp/postal-code": {
+      "types": "./out/jp/postal-code.d.ts",
+      "default": "./out/jp/postal-code.js"
+    },
+    "./jp/prefecture": {
+      "types": "./out/jp/prefecture.d.ts",
+      "default": "./out/jp/prefecture.js"
+    },
+    "./nz/delivery-service": {
+      "types": "./out/nz/delivery-service.d.ts",
+      "default": "./out/nz/delivery-service.js"
+    },
+    "./nz/postcode": {
+      "types": "./out/nz/postcode.d.ts",
+      "default": "./out/nz/postcode.js"
+    },
+    "./us/floor-designator": {
+      "types": "./out/us/floor-designator.d.ts",
+      "default": "./out/us/floor-designator.js"
+    },
+    "./us/military-address": {
+      "types": "./out/us/military-address.d.ts",
+      "default": "./out/us/military-address.js"
+    },
+    "./us/po-box": {
+      "types": "./out/us/po-box.d.ts",
+      "default": "./out/us/po-box.js"
+    },
+    "./us/state": {
+      "types": "./out/us/state.d.ts",
+      "default": "./out/us/state.js"
+    },
+    "./us/street-directional": {
+      "types": "./out/us/street-directional.d.ts",
+      "default": "./out/us/street-directional.js"
+    },
+    "./us/street-suffix": {
+      "types": "./out/us/street-suffix.d.ts",
+      "default": "./out/us/street-suffix.js"
+    },
+    "./us/unit-designator": {
+      "types": "./out/us/unit-designator.d.ts",
+      "default": "./out/us/unit-designator.js"
+    },
+    "./us/zipcode": {
+      "types": "./out/us/zipcode.d.ts",
+      "default": "./out/us/zipcode.js"
     }
   },
   "publishConfig": {
@@ -133,6 +296,166 @@
       "./it": {
         "types": "./out/it/index.d.ts",
         "default": "./out/it/index.js"
+      },
+      "./address-system-conventions": {
+        "types": "./out/address-system-conventions.d.ts",
+        "default": "./out/address-system-conventions.js"
+      },
+      "./gb/postcode": {
+        "types": "./out/gb/postcode.d.ts",
+        "default": "./out/gb/postcode.js"
+      },
+      "./level-semantics": {
+        "types": "./out/level-semantics.d.ts",
+        "default": "./out/level-semantics.js"
+      },
+      "./postcode-systems": {
+        "types": "./out/postcode-systems.d.ts",
+        "default": "./out/postcode-systems.js"
+      },
+      "./au/delivery-service": {
+        "types": "./out/au/delivery-service.d.ts",
+        "default": "./out/au/delivery-service.js"
+      },
+      "./au/level-designator": {
+        "types": "./out/au/level-designator.d.ts",
+        "default": "./out/au/level-designator.js"
+      },
+      "./au/postcode": {
+        "types": "./out/au/postcode.d.ts",
+        "default": "./out/au/postcode.js"
+      },
+      "./au/state": {
+        "types": "./out/au/state.d.ts",
+        "default": "./out/au/state.js"
+      },
+      "./ca/postal-code": {
+        "types": "./out/ca/postal-code.d.ts",
+        "default": "./out/ca/postal-code.js"
+      },
+      "./ca/province": {
+        "types": "./out/ca/province.d.ts",
+        "default": "./out/ca/province.js"
+      },
+      "./ca/street-type": {
+        "types": "./out/ca/street-type.d.ts",
+        "default": "./out/ca/street-type.js"
+      },
+      "./country/country": {
+        "types": "./out/country/country.d.ts",
+        "default": "./out/country/country.js"
+      },
+      "./country/display-names": {
+        "types": "./out/country/display-names.d.ts",
+        "default": "./out/country/display-names.js"
+      },
+      "./country/official-languages": {
+        "types": "./out/country/official-languages.d.ts",
+        "default": "./out/country/official-languages.js"
+      },
+      "./country/reference": {
+        "types": "./out/country/reference.d.ts",
+        "default": "./out/country/reference.js"
+      },
+      "./country/subdivision": {
+        "types": "./out/country/subdivision.d.ts",
+        "default": "./out/country/subdivision.js"
+      },
+      "./de/bundesland": {
+        "types": "./out/de/bundesland.d.ts",
+        "default": "./out/de/bundesland.js"
+      },
+      "./de/postleitzahl": {
+        "types": "./out/de/postleitzahl.d.ts",
+        "default": "./out/de/postleitzahl.js"
+      },
+      "./de/street-type": {
+        "types": "./out/de/street-type.d.ts",
+        "default": "./out/de/street-type.js"
+      },
+      "./fr/cedex": {
+        "types": "./out/fr/cedex.d.ts",
+        "default": "./out/fr/cedex.js"
+      },
+      "./fr/code-postal": {
+        "types": "./out/fr/code-postal.d.ts",
+        "default": "./out/fr/code-postal.js"
+      },
+      "./fr/departement": {
+        "types": "./out/fr/departement.d.ts",
+        "default": "./out/fr/departement.js"
+      },
+      "./fr/region": {
+        "types": "./out/fr/region.d.ts",
+        "default": "./out/fr/region.js"
+      },
+      "./fr/voie": {
+        "types": "./out/fr/voie.d.ts",
+        "default": "./out/fr/voie.js"
+      },
+      "./gb/country": {
+        "types": "./out/gb/country.d.ts",
+        "default": "./out/gb/country.js"
+      },
+      "./gb/postcode-area": {
+        "types": "./out/gb/postcode-area.d.ts",
+        "default": "./out/gb/postcode-area.js"
+      },
+      "./gb/street-type": {
+        "types": "./out/gb/street-type.d.ts",
+        "default": "./out/gb/street-type.js"
+      },
+      "./jp/address-unit": {
+        "types": "./out/jp/address-unit.d.ts",
+        "default": "./out/jp/address-unit.js"
+      },
+      "./jp/postal-code": {
+        "types": "./out/jp/postal-code.d.ts",
+        "default": "./out/jp/postal-code.js"
+      },
+      "./jp/prefecture": {
+        "types": "./out/jp/prefecture.d.ts",
+        "default": "./out/jp/prefecture.js"
+      },
+      "./nz/delivery-service": {
+        "types": "./out/nz/delivery-service.d.ts",
+        "default": "./out/nz/delivery-service.js"
+      },
+      "./nz/postcode": {
+        "types": "./out/nz/postcode.d.ts",
+        "default": "./out/nz/postcode.js"
+      },
+      "./us/floor-designator": {
+        "types": "./out/us/floor-designator.d.ts",
+        "default": "./out/us/floor-designator.js"
+      },
+      "./us/military-address": {
+        "types": "./out/us/military-address.d.ts",
+        "default": "./out/us/military-address.js"
+      },
+      "./us/po-box": {
+        "types": "./out/us/po-box.d.ts",
+        "default": "./out/us/po-box.js"
+      },
+      "./us/state": {
+        "types": "./out/us/state.d.ts",
+        "default": "./out/us/state.js"
+      },
+      "./us/street-directional": {
+        "types": "./out/us/street-directional.d.ts",
+        "default": "./out/us/street-directional.js"
+      },
+      "./us/street-suffix": {
+        "types": "./out/us/street-suffix.d.ts",
+        "default": "./out/us/street-suffix.js"
+      },
+      "./us/unit-designator": {
+        "types": "./out/us/unit-designator.d.ts",
+        "default": "./out/us/unit-designator.js"
+      },
+      "./us/zipcode": {
+        "types": "./out/us/zipcode.d.ts",
+        "default": "./out/us/zipcode.js"
       }
     }
   },
@@ -140,6 +463,7 @@
     "type-fest": "^5.8.0"
   },
   "devDependencies": {
-    "@mailwoman/annotations": "9.0.0"
+    "@mailwoman/annotations": "9.2.0",
+    "@mailwoman/core": "9.2.0"
   }
 }

package/postcode-systems.ts

@@ -68,3 +68,115 @@ export function candidateSystemsForPostcode(postcode: string): SystemCode[] {
 
 	return out
 }
+
+/**
+ * Postcode shapes whose code is UNIT-GRADE — a delivery-walk or street-block unit, categorically tighter than any
+ * locality centroid, so an EXACT hit on one may lead the admin ladder instead of following the locality-first epoch
+ * convention.
+ *
+ * The convention exists because most postal systems are AREA-class: an FR 5-digit zone is coarser than the commune it
+ * contains, so promoting it would trade a good answer for a worse one. Two systems are the other way round, and
+ * membership here is earned by MEASUREMENT of the code's granularity, never by "the code has letters in it":
+ *
+ * - **NL PC6** (`1012 LG`) — ~8 addresses per code; the CBS polygon centroid (#977, the original carve-out).
+ * - **GB unit** (`N7 0BT`) — ~15 addresses per code, 1,751,733 shipped from OS Code-Point Open. Measured 2026-08-10
+ *   against the panel-v2 GB rooftop truth: unit centroid within 1 km on 15/15 rows, median 38 m, max 100 m, while the
+ *   locality centroid the ladder returned instead was 5.1–14.6 km out.
+ * - **CA URBAN LDU** (`M1J 1A8`) — 843,739 six-character codes. Measured on 879 graded rows of the CA OSM-rooftop panel,
+ *   through the production candidate backend, ladder arm against ladder arm:
+ *
+ *   | 732 URBAN rows | p50 | p75 | p90 | ≤1 km | | -------------- | ---: | ---: | ---: | ---: | | locality-first | 2.51
+ *   km | 5.42 km | 9.53 km | 26.4% | | postcode-first | **78 m** | **162 m** | **373 m** | **94.7%** |
+ *
+ *   Closer on 90.4% of them. That is GB's tier on a sample fifty times larger than GB's.
+ *
+ * **CA RURAL is excluded, and the code says which.** Canada Post puts a `0` in the SECOND position of a rural forward
+ * sortation area, so `T0H 1M0` is rural and `M1J 1A8` is not — no lookup required. A rural LDU serves a delivery route
+ * rather than a block face, and it measures like one. On the same panel, the 114 rural rows:
+ *
+ * | 114 RURAL rows | p50       | p75         | p90         | ≤1 km     |
+ * | -------------- | --------: | ----------: | ----------: | --------: |
+ * | locality-first | **929 m** | **2.02 km** | **5.73 km** | **53.5%** |
+ * | postcode-first | 2.08 km   | 4.79 km     | 8.11 km     | 25.4%     |
+ *
+ * Postcode-first is closer on only 26.3% of them, so the pattern below admits `[1-9]` in that position and nothing
+ * else. `509 Main Street South-West Falher AB T0H 1M0` is the worked case: 0.29 km from the locality centroid and 43.18
+ * km from its own postal code.
+ *
+ * The pooled CA number hides that entirely — 0.10 km p50 across both populations reads as a uniform win and is not one.
+ * A tier claim that averages two granularities is the thing this table exists to prevent.
+ *
+ * Lives in codex (per-address-system postal reference) so the Node result assembly (`mailwoman/geocode-core`) and the
+ * demo's pin ranking consume ONE tier definition — the 2026-08-11 staged-repoint e2e measured the two disagreeing.
+ */
+export const UNIT_GRADE_POSTCODE: ReadonlyArray<RegExp> = [
+	// NL PC6 — `1012 LG` / `1012LG`.
+	/^\d{4}\s?[A-Z]{2}$/i,
+	// GB unit — outward (1-2 letters + digit + optional alnum) + inward `\d[A-Z]{2}`, the same shape
+	// `@mailwoman/codex/gb`'s UK_POSTCODE_PATTERN anchors, restated here so this module stays
+	// dependency-free within the package (the slices import THIS, never the reverse).
+	/^[A-Z]{1,2}\d[A-Z\d]?\s?\d[A-Z]{2}$/i,
+	// CA urban LDU — `M1J 1A8`. The `[1-9]` in the second position is the whole tier claim: a `0` there marks a RURAL
+	// forward sortation area, which measures 2.08 km p50 against the locality's 929 m and does not belong here.
+	/^[A-Z][1-9][A-Z]\s?\d[A-Z]\d$/i,
+]
+
+/**
+ * Strip everything but letters and digits, upper-cased — the comparison surface for "did the resolver hit the FULL code
+ * or a coarser stem?". `N7 0BT` and `N70BT` are the same code; `N7` is not.
+ */
+const alnum = (s: string): string => s.replaceAll(/[^\p{L}\p{N}]/gu, "").toUpperCase()
+
+/**
+ * True when a resolved postcode is an EXACT hit on a unit-grade code — the #977 three-way guard, shared by the Node
+ * ladder and the demo pin ranking:
+ *
+ * 1. The PARSED span is a full unit shape ({@link UNIT_GRADE_POSTCODE}), not a stem the user typed;
+ * 2. The node resolved (a coordinate is present — checked by the caller); and
+ * 3. The resolver's own hit is the FULL code, not a coarsened prefix (a 4-digit NL stem or a GB outward district is
+ *    AREA-class, and promoting it is the exact trade the epoch convention forbids).
+ */
+export function isUnitGradePostcodeHit(parsed: string, resolverName: string | undefined): boolean {
+	const value = parsed.trim()
+
+	if (!value || !UNIT_GRADE_POSTCODE.some((re) => re.test(value))) return false
+
+	return alnum(resolverName ?? "") === alnum(value)
+}
+
+/**
+ * Address systems whose AREA-grade postal code is still FINER than the locality containing it — the third granularity
+ * tier, between {@link UNIT_GRADE_POSTCODE} and the locality-first default.
+ *
+ * Whether a postal zone is coarser than its locality is a fact about a country's ADMINISTRATIVE geography, not about
+ * its postal system, and code length does not predict it: FR and DE are both 5-digit and land on opposite sides. France
+ * has ~35,000 communes and one code postal often spans several, so the commune is finer. A German Gemeinde can be
+ * enormous — Berlin is one WOF locality — so the PLZ is finer by a wide margin.
+ *
+ * Membership is earned by a full-panel measurement, the same bar {@link UNIT_GRADE_POSTCODE} sets for CA. Coordinate
+ * p50 on the OpenAddresses panels, locality-first (the default) against the postcode point:
+ *
+ * | country | rows  | locality-first | postcode point | verdict                                                            |
+ * | ------- | ----: | -------------: | -------------: | ------------------------------------------------------------------ |
+ * | **DE**  | 2,997 | 5.84 km        | **1.24 km**    | postcode, on EVERY percentile incl. p99 (21.50 → 10.57)            |
+ * | FR      | 3,000 | **0.97 km**    | 2.64 km        | locality, closer on 77.5% of rows                                  |
+ * | IT      | 2,833 | **1.34 km**    | 3.05 km        | locality, closer on 66.4%                                          |
+ * | ES      | 2,929 | **0.68 km**    | 0.97 km        | locality, but near a coin flip — 46.1% of rows prefer the postcode |
+ * | US      | 577   | **2.28 km**    | 4.15 km        | locality (see below)                                               |
+ *
+ * **The US row is measured on the population production actually sends to the ladder.** Its rooftop cascade is US-only
+ * by construction (`selectAddressPointsDB` composes `address-points-us-<slug>.db`), and it serves 94.2% of US queries,
+ * so only 577 of 10,000 panel rows reach an admin decision at all. Those are the rows no rooftop or interpolation shard
+ * could place, which skews rural — exactly where a locality centroid sits close and a ZIP zone is wide. Measured over
+ * all 10,000 rows instead, the US looks like a postcode-first country (2.41 km vs 3.63); that is a selection effect,
+ * and it is why this table reports 577 rows for the US and full panels for the others, which have no such cascade.
+ */
+export const AREA_POSTCODE_FINER_THAN_LOCALITY: ReadonlySet<string> = new Set(["DE"])
+
+/**
+ * True when this country's area-grade postal code outranks its locality. Absent or unknown country → false, so the
+ * locality-first convention is what an unscoped query gets.
+ */
+export function areaPostcodeLeadsLocality(country: string | undefined): boolean {
+	return country !== undefined && AREA_POSTCODE_FINER_THAN_LOCALITY.has(country.trim().toUpperCase())
+}

package/tools/build-country-surface-lexicon.ts

@@ -64,7 +64,7 @@ const SLOTS = ["country_surface", "country_ambiguous"]
  * Committed output path (a codex-derived artifact, like export-country-surfaces.ts — no argv, so the no-process-globals
  * lint policy holds; codex stays zero-runtime-dep).
  */
-const OUTPUT = resolve(import.meta.dirname, "../../data/gazetteer/country-surface-lexicon-v1.json")
+const OUTPUT = resolve(import.meta.dirname, "../../../data/gazetteer/country-surface-lexicon-v1.json")
 
 /**
  * THE shared word-normalization rule (identical to build-gazetteer-anchor-lexicon.mjs and mirrored in

package/tools/export-country-surfaces.ts

@@ -31,7 +31,7 @@ for (const [iso2, name] of ISO2_TO_NAME) {
 	}
 }
 
-const out = resolve(import.meta.dirname, "../../corpus-python/src/mailwoman_train/data/country-surfaces.json")
+const out = resolve(import.meta.dirname, "../../../corpus-python/src/mailwoman_train/data/country-surfaces.json")
 
 writeFileSync(
 	out,

package/tools/generate-country-population.ts

@@ -0,0 +1,143 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Regenerate `codex/country/population.ts` — the per-country population table — from GeoNames
+ *   `countryInfo.txt` (https://download.geonames.org/export/dump/countryInfo.txt, CC-BY-4.0). The
+ *   output is committed; this tool makes it reproducible (provenance), not a hand-typed dictionary.
+ *
+ *   Why it exists (#1650): WOF carries no readable population for 147 of 237 country records
+ *   (measured against the 2026-08-18 candidate build), so those countries entered every prominence
+ *   race at an asserted ZERO — ranked below any namesake hamlet. The magnitude is what a fame race
+ *   reads, so a census-vintage figure is entirely sufficient; currency of the estimate is not the
+ *   point.
+ *
+ *   Rows whose GeoNames population is 0 are DROPPED rather than emitted: an entry in this table is a
+ *   positive claim, and the consumer's absence branch (`?? undefined`) must stay reachable for
+ *   territories GeoNames itself declines to estimate (the meaning-of-zero rule).
+ *
+ *   Usage: mailwoman dev generate country-population
+ */
+
+import { writeFileSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+
+import { APIClient, pluckResponseData } from "@mailwoman/core/api"
+
+const SOURCE = "https://download.geonames.org/export/dump/countryInfo.txt"
+
+/**
+ * The committed output path, resolved relative to this module (codex/tools/ → codex/country/). See
+ * `generate-country-reference.ts` for why this is `import.meta.url` rather than a `core` path helper (codex is
+ * zero-runtime-dep and `core` already references `codex` — importing core here would cycle the project graph).
+ */
+const DEFAULT_OUT = fileURLToPath(new URL("../country/population.ts", import.meta.url))
+
+/**
+ * Tab positions this tool reads from `countryInfo.txt`'s 19-column rows. Named so the parse states which columns it
+ * believes in; a GeoNames format change fails the count guard below rather than silently reading the wrong column.
+ */
+const COLUMN_ISO2 = 0
+const COLUMN_POPULATION = 7
+const MINIMUM_COLUMNS = 8
+
+/**
+ * GeoNames publishes ~250 countries/territories; a parse recovering fewer than this read the wrong column or a
+ * truncated body, and the guard fails loudly instead of committing a hollow table.
+ */
+const MINIMUM_PLAUSIBLE_COUNTRIES = 200
+
+/**
+ * Numbers below five digits are emitted bare — the house numeric-separator style groups by three and only from five
+ * digits up (`8450`, not `8_450`).
+ */
+const SEPARATOR_MINIMUM = 10_000
+
+/**
+ * Options for {@linkcode generateCountryPopulation}.
+ */
+export interface GenerateCountryPopulationOptions {
+	/**
+	 * Output path override. Default: `codex/country/population.ts` (the committed table).
+	 */
+	out?: string
+}
+
+/**
+ * Summary returned by {@linkcode generateCountryPopulation}.
+ */
+export interface GenerateCountryPopulationSummary {
+	countries: number
+	outPath: string
+}
+
+/**
+ * Fetch GeoNames `countryInfo.txt` and regenerate the committed `COUNTRY_POPULATION` table.
+ */
+export async function generateCountryPopulation(
+	options: GenerateCountryPopulationOptions = {},
+	report?: (line: string) => void
+): Promise<GenerateCountryPopulationSummary> {
+	const outPath = options.out ?? DEFAULT_OUT
+
+	// `responseType: "text"` because the source is a tab-separated dump, not JSON.
+	const text = await new APIClient({ displayName: "geonames-country-info", retry: true })
+		.fetch<string>({ url: SOURCE, responseType: "text" })
+		.then(pluckResponseData)
+
+	const rows: Record<string, number> = {}
+
+	// oxlint-disable-next-line mailwoman/prefer-spliterator -- countryInfo.txt is ~35 kB and bounded (~300 rows)
+	for (const line of text.split("\n")) {
+		if (!line || line.startsWith("#")) continue
+		// oxlint-disable-next-line mailwoman/prefer-spliterator -- one 19-column row
+		const columns = line.split("\t")
+
+		if (columns.length < MINIMUM_COLUMNS) continue
+		const alpha2 = columns[COLUMN_ISO2]!.trim()
+		const population = Number(columns[COLUMN_POPULATION])
+
+		if (!/^[A-Z]{2}$/.test(alpha2)) continue
+
+		if (!Number.isFinite(population) || population <= 0) continue
+
+		rows[alpha2] = population
+	}
+
+	if (Object.keys(rows).length < MINIMUM_PLAUSIBLE_COUNTRIES) {
+		throw new Error(`generateCountryPopulation: only ${Object.keys(rows).length} rows parsed — format drift?`)
+	}
+
+	const body = Object.keys(rows)
+		.toSorted()
+		.map((k) => {
+			const n = rows[k]!
+			const literal = n >= SEPARATOR_MINIMUM ? n.toLocaleString("en-US").replaceAll(",", "_") : String(n)
+
+			return `\t${k}: ${literal},`
+		})
+		.join("\n")
+
+	const header = `/**
+ * @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>> = {`
+
+	writeFileSync(outPath, `${header}\n${body}\n}\n`)
+	report?.(`wrote ${outPath} (${Object.keys(rows).length} countries)`)
+
+	return { countries: Object.keys(rows).length, outPath }
+}

package/tools/generate-country-reference.ts

@@ -17,6 +17,8 @@
 import { writeFileSync } from "node:fs"
 import { fileURLToPath } from "node:url"
 
+import { APIClient, pluckResponseData } from "@mailwoman/core/api"
+
 const SOURCE = "https://raw.githubusercontent.com/mledoze/countries/master/countries.json"
 
 /**
@@ -97,10 +99,10 @@ export async function generateCountryReference(
 	report?: (line: string) => void
 ): Promise<GenerateCountryReferenceSummary> {
 	const outPath = options.out ?? DEFAULT_OUT
-	const response = await fetch(SOURCE)
 
-	if (!response.ok) throw new Error(`fetch ${SOURCE} failed: ${response.status}`)
-	const countries = (await response.json()) as MledozeCountry[]
+	const countries = await new APIClient({ displayName: "mledoze-countries", retry: true })
+		.fetch<MledozeCountry[]>({ url: SOURCE })
+		.then(pluckResponseData)
 
 	const rows: Record<string, CountryReferenceEntry> = {}