@mailwoman/codex 9.1.0 → 9.3.0

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

@@ -25,16 +25,26 @@ export {
 	ADDRESS_SYSTEM_CONVENTIONS,
 	conventionsForSystem,
 	type AddressSystemConventions,
-} from "./address-system-conventions.ts"
+} from "#address-system-conventions"
 
-export * from "./normalize.ts"
-export * as au from "./au/index.ts"
-export * as ca from "./ca/index.ts"
-export * as de from "./de/index.ts"
-export * as fr from "./fr/index.ts"
-export * as gb from "./gb/index.ts"
-export * as jp from "./jp/index.ts"
-export * as levels from "./level-semantics.ts"
-export * as nz from "./nz/index.ts"
-export { candidateSystemsForPostcode, type SystemCode } from "./postcode-systems.ts"
-export * as us from "./us/index.ts"
+export * from "#normalize"
+export * as au from "#au/index"
+export * as ca from "#ca/index"
+export * as de from "#de/index"
+export * as fr from "#fr/index"
+export * as gb from "#gb/index"
+export * as jp from "#jp/index"
+export * as levels from "#level-semantics"
+export * as nz from "#nz/index"
+
+export {
+	AREA_POSTCODE_FINER_THAN_LOCALITY,
+	areaPostcodeLeadsLocality,
+	candidateSystemsForPostcode,
+	isUnitGradePostcodeHit,
+	SYSTEM_CODES,
+	type SystemCode,
+	UNIT_GRADE_POSTCODE,
+} from "#postcode-systems"
+
+export * as us from "#us/index"

package/{it → lib/it}/cap.ts

@@ -3,7 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Italian postal codes (Codice di Avviamento Postale, CAP): the branded type and the shape.
+ *   Italian postcodes (Codice di Avviamento Postale, CAP): the branded type and the shape.
  *
  *   Five digits like the Spanish, French and German forms, but do NOT infer a province from the
  *   leading digits the way `es/codigo-postal.ts` documents for Spain. Italy's large cities are
@@ -15,7 +15,7 @@
 import type { Tagged } from "type-fest"
 
 /**
- * An Italian postal code: five digits (`00184` is Rome, Rione Monti).
+ * An Italian postcode: five digits (`00184` is Rome, Rione Monti).
  *
  * @category Postal
  * @type string
@@ -30,10 +30,28 @@ export type CAP = Tagged<string, "CAP">
 export const CAP_PATTERN = /^\d{5}$/
 
 /**
- * Narrow a string to a {@link CAP}, or `null` when it is not one.
+ * Normalize a CAP surface form to the bare five digits: trim surrounding whitespace (`" 00184 "` → `"00184"`). Returns
+ * null when the result is not a five-digit code.
  */
-export function parseCAP(input: string): CAP | null {
-	const s = input.trim()
+export function normalizeCAP(raw: unknown): CAP | null {
+	if (typeof raw !== "string") return null
+	const s = raw.trim()
 
 	return CAP_PATTERN.test(s) ? (s as CAP) : null
 }
+
+/**
+ * Type-predicate for a (normalized) Italian CAP.
+ */
+export function isCAP(input: unknown): input is CAP {
+	return typeof input === "string" && CAP_PATTERN.test(input)
+}
+
+/**
+ * Narrow a string to a {@link CAP}, or `null` when it is not one.
+ *
+ * @deprecated Use {@link normalizeCAP}.
+ */
+export function parseCAP(input: string): CAP | null {
+	return normalizeCAP(input)
+}

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

@@ -6,4 +6,4 @@
  *   Italian (IT) address-system reference data.
  */
 
-export * from "./cap.ts"
+export * from "#it/cap"

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

@@ -3,11 +3,11 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The Japanese address system (Japan Post / ISO 3166-2:JP): the 47 prefectures, the postal code
+ *   The Japanese address system (Japan Post / ISO 3166-2:JP): the 47 prefectures, the postcode
  *   that is the country's most reliable geographic anchor, and the address-unit markers that stand
  *   in for the street names Japan does not use.
  */
 
-export * from "./address-unit.ts"
-export * from "./postal-code.ts"
-export * from "./prefecture.ts"
+export * from "#jp/address-unit"
+export * from "#jp/postal-code"
+export * from "#jp/prefecture"

package/{jp → lib/jp}/postal-code.ts

@@ -3,7 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Japanese postal codes (郵便番号, yūbin-bangō): the branded type, the shape, normalization, and the
+ *   Japanese postcodes (郵便番号, yūbin-bangō): the branded type, the shape, normalization, and the
  *   first-digit → coarse-region prior.
  *
  *   This file is the far end of a spectrum whose other end is `us/zipcode.ts`. A US address leans on
@@ -16,7 +16,7 @@
  *       navigate by named streets; you navigate by nested administrative areas and numbered
  *       blocks/lots (丁目 / 番地 / 号 — see `address-unit.ts`).
  *
- *   With no street name to anchor on and a reverse field order, the **postal code is the single most
+ *   With no street name to anchor on and a reverse field order, the **postcode is the single most
  *   reliable geographic anchor** for a Japanese address — it pins the chōme-level area directly,
  *   far tighter than a US ZIP pins a US address. So where the US parser treats the postcode as a
  *   tie-breaker behind the street, the Japan parser should treat it as the primary key.
@@ -25,9 +25,9 @@
 import type { Tagged } from "type-fest"
 
 /**
- * A Japanese postal code: three digits, a hyphen, then four digits (`100-0001`), conventionally written after the 〒
- * mark (`〒100-0001`). Branded so a normalized code is distinct from an arbitrary string — the 7-digit shape alone does
- * not prove a code is real, only well-formed.
+ * A Japanese postcode: three digits, a hyphen, then four digits (`100-0001`), conventionally written after the 〒 mark
+ * (`〒100-0001`). Branded so a normalized code is distinct from an arbitrary string — the 7-digit shape alone does not
+ * prove a code is real, only well-formed.
  *
  * @category Postal
  * @type string
@@ -57,17 +57,17 @@ export function normalizeJpPostalCode(raw: unknown): PostalCode | null {
 }
 
 /**
- * Type-predicate for a Japanese postal code (hyphen optional, `100-0001` or `1000001`).
+ * Type-predicate for a Japanese postcode (hyphen optional, `100-0001` or `1000001`).
  */
 export function isJpPostalCode(input: unknown): input is PostalCode {
 	return typeof input === "string" && JP_POSTAL_CODE_PATTERN.test(input)
 }
 
 /**
- * First digit of the postal code → a coarse region label. Japan Post's numbering grows roughly outward from Tokyo
- * (`1xx`) and is **approximate** at this granularity — a single leading digit spans large, irregular areas and the
- * boundaries are postal-routing, not administrative. Use it as a weak prior, never as a hard region assignment; the
- * full code is what actually anchors the address.
+ * First digit of the postcode → a coarse region label. Japan Post's numbering grows roughly outward from Tokyo (`1xx`)
+ * and is **approximate** at this granularity — a single leading digit spans large, irregular areas and the boundaries
+ * are postal-routing, not administrative. Use it as a weak prior, never as a hard region assignment; the full code is
+ * what actually anchors the address.
  *
  * Approximate — the labels below are illustrative routing regions, not precise prefecture sets.
  */
@@ -85,7 +85,7 @@ export const JP_FIRST_DIGIT_REGION: Record<string, string> = {
 }
 
 /**
- * The coarse region label for a postal code's first digit, or null if the input is not a Japanese postal code. A weak,
+ * The coarse region label for a postcode's first digit, or null if the input is not a Japanese postcode. A weak,
  * approximate prior (see {@link JP_FIRST_DIGIT_REGION}); the full code anchors the address.
  */
 export function firstDigitRegion(postalCode: unknown): string | null {

package/{jp → lib/jp}/prefecture.ts

@@ -6,7 +6,10 @@
  *   The 47 Japanese prefectures (都道府県, todōfuken), keyed by their ISO 3166-2:JP code — the two-digit
  *   numeric string `"01"`..`"47"` standing in for `JP-01`..`JP-47`.
  *
- *   The contrast with `fr/region.ts`, `de/bundesland.ts`, and `us/state.ts` is in the name itself.
+ *   Compared to `fr/region.ts`, `de/bundesland.ts`, and `us/state.ts`,
+ * 	 this is a more complex case because the top-level admin unit comes in four legally distinct flavours,
+ *   and the prefecture name is written on the address line (not inferred from postcode).
+ *
  *   "都道府県" is four kanji because the top-level admin unit comes in four legally distinct flavours,
  *   even though all 47 are peers in practice:
  *
@@ -23,6 +26,8 @@
  *   `postal-code.ts` for why the postcode is nonetheless the single most reliable anchor.
  */
 
+import { foldToken } from "#normalize"
+
 /**
  * A to/dō/fu/ken classification of the top-level admin unit.
  */
@@ -130,10 +135,7 @@ export function isJapanesePrefectureCode(input: unknown): input is JapanesePrefe
  * them. We never strip from an unseparated bare name, so `kyoto` stays `kyoto`.
  */
 function foldRomaji(s: string): string {
-	const lowered = s
-		.toLowerCase()
-		.normalize("NFD")
-		.replaceAll(/[\u0300-\u036F]/g, "")
+	const lowered = foldToken(s)
 
 	// Strip an appended type-suffix only when a separator (hyphen / space / middle dot) precedes it.
 	const desuffixed = lowered.replace(/[-\s·][\s]*(to|do|fu|ken)$/, "")

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

@@ -41,7 +41,7 @@ export function wordNorm(s: string): string {
 	return s
 		.split(/\s+/)
 		.map((w) => w.replaceAll(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, ""))
-		.filter(Boolean)
+		.filter((w) => w.length > 0)
 		.join(" ")
 }
 
@@ -51,3 +51,17 @@ export function wordNorm(s: string): string {
 export function wordNormLower(s: string): string {
 	return wordNorm(s).toLowerCase()
 }
+
+/**
+ * Fold a single token to its lowercase, diacritic-free form: lower-cased, NFD-decomposed, combining marks stripped —
+ * `"Côte"` → `"cote"`, `"Tōkyō"` → `"tokyo"`.
+ *
+ * The shared core of the per-country token matchers. Unlike {@link foldName} it does not touch punctuation or whitespace
+ * — each matcher layers its own character filtering (letters-only, hyphen-keeping, suffix-stripping) on top.
+ */
+export function foldToken(s: string): string {
+	return s
+		.toLowerCase()
+		.normalize("NFD")
+		.replaceAll(/[\u0300-\u036F]/g, "")
+}

package/{nz → lib/nz}/delivery-service.ts

@@ -33,7 +33,7 @@
  *   mail, accessed 2026-06-11) name only the six types above. However, real NZ mail and the postal
  *   arena's gold rows carry "Private Box" as a colloquial synonym for a numbered PO Box (same
  *   numbered format, different label). Operator ruling 2026-06-11: "Private Box = recognize-as-used
- *   — codex documents it unofficial/colloquial WITH the 'officially invalid' citation; the shard
+ *   — codex documents it unofficial/colloquial WITH the 'officially invalid' citation; the extract
  *   teaches recognition (validity and recognition are separate disciplines, same as the AU legacy
  *   flags)." This is encoded in {@link NZ_PRIVATE_BOX_ALIAS} — a distinct export from
  *   {@link NZ_DELIVERY_SERVICE_TYPES} so callers can choose whether to include the unofficial form.

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

@@ -8,5 +8,5 @@
  *   Restante) and the 4-digit postcode. NZ addresses carry no state/region line.
  */
 
-export * from "./delivery-service.ts"
-export * from "./postcode.ts"
+export * from "#nz/delivery-service"
+export * from "#nz/postcode"

package/lib/postcode-systems.ts

@@ -0,0 +1,198 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The inverse of the per-slice postcode patterns: given a postcode string, which address SYSTEMS
+ *   could it belong to? Each codex slice owns its own postcode shape (`us` accepts
+ *   `\d{5}(-\d{4})?`, `ca` accepts `A1A 1A1`, `jp` accepts `NNN-NNNN`, …); this is the single place
+ *   that asks all of them at once and collects the matches.
+ *
+ *   It is the shared source of truth for "which systems can this shape be" — consumed by the postcode
+ *   anchor (to narrow which systems' street vocabularies it checks) and, in time, by the runtime
+ *   pipeline's `@mailwoman/locale-hint` stage (so its format→locale scoring derives from the same patterns rather than
+ *   a second, divergent copy). The point is to unify the DATA, not to couple the modules: callers
+ *   depend on this pure function, never on each other.
+ *
+ *   Note this is a SHAPE test, not a gazetteer-membership test. A bare `68161` matches the US,
+ *   German, French, Spanish and Italian 5-digit shapes, so it returns `["us", "de", "fr", "es", "it"]` —
+ *   the shape alone cannot split the numeric-postcode systems. The anchor uses real gazetteer membership for the finer
+ *   call; this function answers the coarser, model-free "which systems is this shape even eligible
+ *   for".
+ */
+
+import { normalizeAuPostcode } from "#au/index"
+import { normalizeCaPostalCode } from "#ca/index"
+import { normalizePLZ } from "#de/index"
+import { normalizeCodigoPostal } from "#es/index"
+import { normalizeCodePostal } from "#fr/index"
+import { normalizeUkPostcode } from "#gb/index"
+import { normalizeCAP } from "#it/index"
+import { normalizeJpPostalCode } from "#jp/index"
+import { normalizeNZPostcode } from "#nz/index"
+import { isZipCode } from "#us/index"
+
+/**
+ * A codex address-system code — the subpath under `@mailwoman/codex/<system>`.
+ */
+export type SystemCode = "us" | "de" | "fr" | "es" | "it" | "ca" | "gb" | "jp" | "au" | "nz"
+
+/**
+ * Per-system membership test: each entry returns true when the string is accepted by that system's own postcode shape
+ * (after that system's normalization — so `D-68161` reaches `de`, `1012 LM` reaches nothing here since NL has no slice
+ * yet, etc.). Ordered for a stable, alphabetical-ish result.
+ */
+const SYSTEM_ACCEPTS: ReadonlyArray<readonly [SystemCode, (s: string) => boolean]> = [
+	["us", (s) => isZipCode(s)],
+	["de", (s) => normalizePLZ(s) !== null],
+	["fr", (s) => normalizeCodePostal(s) !== null],
+	["es", (s) => normalizeCodigoPostal(s) !== null],
+	["it", (s) => normalizeCAP(s) !== null],
+	["ca", (s) => normalizeCaPostalCode(s) !== null],
+	["gb", (s) => normalizeUkPostcode(s) !== null],
+	["jp", (s) => normalizeJpPostalCode(s) !== null],
+	["au", (s) => normalizeAuPostcode(s) !== null],
+	["nz", (s) => normalizeNZPostcode(s) !== null],
+]
+
+/**
+ * Every address system with a postcode shape, in {@link SYSTEM_ACCEPTS} order. The one list a consumer that needs the
+ * universe of systems (rather than the systems a given code fits) should read, so it cannot drift from the table.
+ */
+export const SYSTEM_CODES: readonly SystemCode[] = SYSTEM_ACCEPTS.map(([system]) => system)
+
+/**
+ * Every address system whose own postcode shape accepts `postcode`. Empty when no system recognizes the shape (e.g. a
+ * bare `27`, or a 7-digit run). O(number of systems) — a handful of cheap regex tests, run only on the few
+ * postcode-shaped spans an address contains.
+ */
+export function candidateSystemsForPostcode(postcode: string): SystemCode[] {
+	if (typeof postcode !== "string" || !postcode.length) return []
+	const out: SystemCode[] = []
+
+	for (const [system, accepts] of SYSTEM_ACCEPTS) {
+		if (accepts(postcode)) {
+			out.push(system)
+		}
+	}
+
+	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)                                                   |
+ * | **JP**  | 586   | 4.93 km        | **0.48 km**    | postcode, closer on 97.3% of rows (p90 13.55 → 1.21, p99 19.63 → 3.54) |
+ *
+ * **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
+ * extract 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.
+ *
+ * **The JP row is the JP board through the served path** (`jp-served-resolve.run.ts`, 2,000 rows, seed 42): the 586
+ * rows carrying a postcode the candidate table keys, graded on the row's own entrance point — the locality-first answer
+ * is the municipality centroid, the postcode answer the code's 町域 centroid from the WOF extract.
+ */
+export const AREA_POSTCODE_FINER_THAN_LOCALITY: ReadonlySet<string> = new Set(["DE", "JP"])
+
+/**
+ * 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 → lib/tools}/build-country-surface-lexicon.ts

@@ -34,18 +34,19 @@
  *
  *   Source of truth: `@mailwoman/codex` (COUNTRY_SURFACE_FORMS + ISO2_TO_NAME) — the SAME data the
  *   corpus-python bridge `country-surfaces.json` is generated from (export-country-surfaces.ts), so
- *   the channel and the corpus shard synthesizer cannot diverge on what a country surface IS.
+ *   the channel and the corpus extract synthesizer cannot diverge on what a country surface IS.
  *
  *   Output: data/gazetteer/country-surface-lexicon-v1.json (small, committed, provenance-tracked).
  *   Regenerate: `node codex/tools/build-country-surface-lexicon.ts`
  */
 
-import { mkdirSync, writeFileSync } from "node:fs"
-import { dirname, resolve } from "node:path"
+import { makeDirectories, writeLocalTextFile } from "@mailwoman/core/fs/writers"
+import { repoRootPath } from "@mailwoman/core/paths"
+import { dirname } from "path-ts"
 
-import { COUNTRY_SURFACE_FORMS, ISO2_TO_NAME } from "../country/country.ts"
-import { wordNorm, wordNormLower } from "../normalize.ts"
-import { US_STATE_ABBREVIATIONS, US_STATE_NAMES } from "../us/state.ts"
+import { COUNTRY_SURFACE_FORMS, ISO2_TO_NAME } from "#country/country"
+import { wordNorm, wordNormLower } from "#normalize"
+import { US_STATE_ABBREVIATIONS, US_STATE_NAMES } from "#us/state"
 
 /**
  * Ambiguous entries printed before the list is truncated.
@@ -64,7 +65,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 = repoRootPath("data", "gazetteer", "country-surface-lexicon-v1.json")
 
 /**
  * THE shared word-normalization rule (identical to build-gazetteer-anchor-lexicon.mjs and mirrored in
@@ -167,8 +168,8 @@ const lexicon = {
 	code_entries: Object.fromEntries([...codeEntries].toSorted(([a], [b]) => a.localeCompare(b))),
 }
 
-mkdirSync(dirname(OUTPUT), { recursive: true })
-writeFileSync(OUTPUT, JSON.stringify(lexicon, null, 1) + "\n")
+await makeDirectories(dirname(OUTPUT))
+await writeLocalTextFile(JSON.stringify(lexicon, null, 1) + "\n", OUTPUT)
 
 process.stderr.write(
 	`wrote ${OUTPUT}: ${entries.size} entries + ${codeEntries.size} code_entries, ` +

package/{tools → lib/tools}/export-country-surfaces.ts

@@ -4,7 +4,7 @@
  * @author Teffen Ellis, et al.
  *
  *   codex → corpus-python bridge: emit the authoritative country surface forms as JSON so the Python
- *   shard generators can synthesize address tails ("…, USA" / "…, United States of America") without
+ *   extract generators can synthesize address tails ("…, USA" / "…, United States of America") without
  *   re-deriving the country name/alias data. `@mailwoman/codex` stays the single source of truth
  *   (COUNTRY_SURFACE_FORMS + ISO2_TO_NAME, salvaged from isp-nexus spatial/countries); this writes a
  *   snapshot the language boundary can't import directly.
@@ -12,10 +12,10 @@
  *   Regenerate: `node codex/tools/export-country-surfaces.ts` (writes the corpus-python data file).
  */
 
-import { writeFileSync } from "node:fs"
-import { resolve } from "node:path"
+import { writeLocalTextFile } from "@mailwoman/core/fs/writers"
+import { repoRootPath } from "@mailwoman/core/paths"
 
-import { COUNTRY_SURFACE_FORMS, ISO2_TO_NAME } from "../country/country.ts"
+import { COUNTRY_SURFACE_FORMS, ISO2_TO_NAME } from "#country/country"
 
 // Merge: rich surface forms where the codex curates them, else the canonical English name for every
 // ISO 3166-1 alpha-2. Canonical-name-first (the codex's own ordering) so the common form leads.
@@ -31,10 +31,9 @@ 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 = repoRootPath("corpus-python", "src", "mailwoman_train", "data", "country-surfaces.json")
 
-writeFileSync(
-	out,
+await writeLocalTextFile(
 	JSON.stringify(
 		{
 			_generated: "codex/tools/export-country-surfaces.ts from @mailwoman/codex COUNTRY_SURFACE_FORMS + ISO2_TO_NAME",
@@ -42,7 +41,8 @@ writeFileSync(
 		},
 		null,
 		2
-	) + "\n"
+	) + "\n",
+	out
 )
 
 process.stderr.write(`wrote ${Object.keys(surfaces).length} countries → ${out}\n`)