@mailwoman/codex 7.2.0 → 7.2.1

package/tools/export-country-surfaces.ts

@@ -0,0 +1,46 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @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
+ *   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.
+ *
+ *   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 { COUNTRY_SURFACE_FORMS, ISO2_TO_NAME } from "../country/country.ts"
+
+// 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.
+const surfaces: Record<string, string[]> = {}
+
+for (const [iso2, forms] of Object.entries(COUNTRY_SURFACE_FORMS)) {
+	surfaces[iso2] = [...forms]
+}
+
+for (const [iso2, name] of ISO2_TO_NAME) {
+	if (!surfaces[iso2]) {
+		surfaces[iso2] = [name]
+	}
+}
+
+const out = resolve(import.meta.dirname, "../../corpus-python/src/mailwoman_train/data/country-surfaces.json")
+writeFileSync(
+	out,
+	JSON.stringify(
+		{
+			_generated: "codex/tools/export-country-surfaces.ts from @mailwoman/codex COUNTRY_SURFACE_FORMS + ISO2_TO_NAME",
+			surfaces,
+		},
+		null,
+		2
+	) + "\n"
+)
+process.stderr.write(`wrote ${Object.keys(surfaces).length} countries → ${out}\n`)

package/tools/generate-country-reference.ts

@@ -0,0 +1,153 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Regenerate `codex/country/reference-data.ts` — the per-country calling code (E.164) + currency
+ *   (ISO 4217) table — from mledoze/countries (https://github.com/mledoze/countries, ODbL). The
+ *   output is committed; this tool makes it reproducible (provenance), not a hand-typed dictionary.
+ *
+ *   Calling-code rule: mledoze splits the code as `idd.root` + `idd.suffixes`. For most countries a
+ *   single suffix completes the code (GB `+4` + `4` = 44); NANP members share root `+1` with their
+ *   area code as the suffix, so they map to 1.
+ *
+ *   Usage: mailwoman dev generate country-reference
+ */
+
+import { writeFileSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+
+const SOURCE = "https://raw.githubusercontent.com/mledoze/countries/master/countries.json"
+
+/**
+ * The committed output path, resolved relative to this module (codex/tools/ → codex/country/). The codegen is
+ * repo-only, and in the repo `@mailwoman/codex/tools` always loads from source via the `node` exports condition, so
+ * `import.meta.url` points at the source tree. (`@mailwoman/core`'s `repoRootPath` would also work, but 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/reference-data.ts", import.meta.url))
+
+/** A single country record from mledoze/countries, narrowed to the fields this tool reads. */
+interface MledozeCountry {
+	cca2?: string
+	idd?: { root?: string; suffixes?: string[] }
+	currencies?: Record<string, { name?: string; symbol?: string }>
+}
+
+/** The emitted per-country reference row. */
+interface CountryReferenceEntry {
+	callingCode?: number
+	currency?: { isoCode: string; name?: string; symbol?: string }
+}
+
+/** Options for {@linkcode generateCountryReference}. */
+export interface GenerateCountryReferenceOptions {
+	/** Output path override. Default: `codex/country/reference-data.ts` (the committed table). */
+	out?: string
+}
+
+/** Summary returned by {@linkcode generateCountryReference}. */
+export interface GenerateCountryReferenceSummary {
+	countries: number
+	outPath: string
+}
+
+function callingCode(country: MledozeCountry): number | undefined {
+	const root = (country.idd?.root ?? "").replace("+", "")
+	const suffixes = country.idd?.suffixes ?? []
+
+	if (!root) return undefined
+
+	if (root === "1") return 1
+
+	if (suffixes.length === 1) {
+		const n = Number(root + suffixes[0])
+
+		return Number.isFinite(n) ? n : undefined
+	}
+	const n = Number(root)
+
+	return Number.isFinite(n) ? n : undefined
+}
+
+const serialize = (o: CountryReferenceEntry): string =>
+	JSON.stringify(o, null, 0)
+		.replace(/"isoCode"/g, "isoCode")
+		.replace(/"callingCode"/g, "callingCode")
+		.replace(/"currency"/g, "currency")
+		.replace(/"name"/g, "name")
+		.replace(/"symbol"/g, "symbol")
+
+/** Fetch mledoze/countries and regenerate the committed `COUNTRY_REFERENCE` table. */
+export async function generateCountryReference(
+	options: GenerateCountryReferenceOptions = {},
+	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 rows: Record<string, CountryReferenceEntry> = {}
+
+	for (const country of countries) {
+		const alpha2 = country.cca2
+
+		if (!alpha2) continue
+		const entry: CountryReferenceEntry = {}
+		const cc = callingCode(country)
+
+		if (cc != null) {
+			entry.callingCode = cc
+		}
+		const currencyCodes = Object.keys(country.currencies ?? {}).sort()
+
+		if (currencyCodes.length) {
+			const code = currencyCodes[0]!
+			const info = country.currencies![code] ?? {}
+			entry.currency = { isoCode: code }
+
+			if (info.name) {
+				entry.currency.name = info.name
+			}
+
+			if (info.symbol) {
+				entry.currency.symbol = info.symbol
+			}
+		}
+
+		if (Object.keys(entry).length) {
+			rows[alpha2] = entry
+		}
+	}
+
+	const body = Object.keys(rows)
+		.sort()
+		.map((k) => `\t${k}: ${serialize(rows[k]!)},`)
+		.join("\n")
+
+	const header = `/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   GENERATED — do not edit by hand. Country calling codes (E.164) + currencies (ISO 4217), derived
+ *   from mledoze/countries (https://github.com/mledoze/countries, ODbL). NANP members map to 1.
+ *   Regenerate with: mailwoman dev generate country-reference
+ */
+
+/** Static per-country reference: calling code + currency. */
+export interface CountryReference {
+	callingCode?: number
+	currency?: { isoCode: string; name?: string; symbol?: string }
+}
+
+/** ISO 3166-1 alpha-2 → reference. */
+export const COUNTRY_REFERENCE: Record<string, CountryReference> = {`
+
+	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-official-languages.ts

@@ -0,0 +1,188 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Regenerates `codex/country/official-languages.ts` from Unicode CLDR supplemental data
+ *   (territoryInfo `_officialStatus` + languageAlias). The emitted table is the #936 ingest bit's
+ *   authority for "is this name row in an official language of its country?" — consumed by the
+ *   gazetteer builders (`mailwoman gazetteer build`, `@mailwoman/resolver-wof-sqlite`'s GeoNames
+ *   fold), never at query time.
+ *
+ *   Each language is emitted under EVERY ISO-639 spelling CLDR aliases to it (fi + fin, sv + swe)
+ *   so consumers can test WOF's 639-3 tags, Overture's BCP-47 keys, and GeoNames' mixed 2/3-letter
+ *   codes without a mapping step.
+ *
+ *   Usage: mailwoman dev generate official-languages [--cldr-dir <dir>] [--cldr-version 47.0.0]
+ *
+ *   With `cldrDir`, reads cldr-territoryInfo.json + cldr-aliases.json from disk; otherwise fetches
+ *   the pinned cldr-core release from jsdelivr.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+/**
+ * The committed output path, resolved relative to this module (codex/tools/ → codex/country/). The codegen is
+ * repo-only, and in the repo `@mailwoman/codex/tools` always loads from source via the `node` exports condition, so
+ * `import.meta.url` points at the source tree.
+ */
+const DEFAULT_OUT = fileURLToPath(new URL("../country/official-languages.ts", import.meta.url))
+
+/** Options for {@linkcode generateOfficialLanguages}. */
+export interface GenerateOfficialLanguagesOptions {
+	/** Read cldr-territoryInfo.json + cldr-aliases.json from this directory instead of fetching. */
+	cldrDir?: string
+	/** Pinned cldr-core release fetched from jsdelivr when {@linkcode GenerateOfficialLanguagesOptions.cldrDir} is absent. */
+	cldrVersion?: string
+	/** Output path override. Default: `codex/country/official-languages.ts` (the committed table). */
+	out?: string
+}
+
+/** Summary returned by {@linkcode generateOfficialLanguages}. */
+export interface GenerateOfficialLanguagesSummary {
+	territories: number
+	cldrVersion: string
+	outPath: string
+}
+
+interface LanguagePopulation {
+	_officialStatus?: string
+}
+
+async function loadCLDR(file: string, cldrDir: string | undefined, cldrVersion: string): Promise<unknown> {
+	if (cldrDir) return JSON.parse(readFileSync(join(cldrDir, `cldr-${file}.json`), "utf8"))
+	const url = `https://cdn.jsdelivr.net/npm/cldr-core@${cldrVersion}/supplemental/${file}.json`
+	const res = await fetch(url)
+
+	if (!res.ok) throw new Error(`${url}: HTTP ${res.status}`)
+
+	return res.json()
+}
+
+/** Regenerate the committed `OFFICIAL_LANGUAGES` table from CLDR supplemental data. */
+export async function generateOfficialLanguages(
+	options: GenerateOfficialLanguagesOptions = {},
+	report?: (line: string) => void
+): Promise<GenerateOfficialLanguagesSummary> {
+	const cldrVersion = options.cldrVersion ?? "47.0.0"
+	const outPath = options.out ?? DEFAULT_OUT
+
+	const territoryInfo = (
+		(await loadCLDR("territoryInfo", options.cldrDir, cldrVersion)) as Record<
+			string,
+			Record<string, Record<string, unknown>>
+		>
+	).supplemental!.territoryInfo as Record<string, { languagePopulation?: Record<string, LanguagePopulation> }>
+	const aliasesDoc = (await loadCLDR("aliases", options.cldrDir, cldrVersion)) as {
+		supplemental: { metadata: { alias: { languageAlias: Record<string, { _replacement?: string }> } } }
+	}
+	const languageAlias = aliasesDoc.supplemental.metadata.alias.languageAlias
+
+	// canonical code → every plain 2-3 letter alias spelling that maps to it (fi gains "fin")
+	const spellingsOf = new Map<string, Set<string>>()
+
+	for (const [alias, entry] of Object.entries(languageAlias)) {
+		const canon = entry._replacement
+
+		if (!canon || !/^[a-z]{2,3}$/.test(alias)) continue
+		let set = spellingsOf.get(canon)
+
+		if (!set) {
+			spellingsOf.set(canon, (set = new Set()))
+		}
+		set.add(alias)
+	}
+
+	const table: Record<string, { official: string[]; regional?: string[] }> = {}
+
+	for (const territory of Object.keys(territoryInfo).sort()) {
+		if (!/^[A-Z]{2}$/.test(territory)) continue
+		const pops = territoryInfo[territory]!.languagePopulation
+
+		if (!pops) continue
+		const official = new Set<string>()
+		const regional = new Set<string>()
+
+		for (const [lang, data] of Object.entries(pops)) {
+			const status = data._officialStatus
+
+			if (!status) continue
+			// CLDR keys can carry script subtags ("zh_Hant") — name tags use the base language.
+			const base = lang.split("_")[0]!
+			const spellings = [base, ...(spellingsOf.get(base) ?? [])].sort()
+
+			if (status === "official" || status === "de_facto_official") {
+				for (const s of spellings) {
+					official.add(s)
+				}
+			} else if (status === "official_regional") {
+				for (const s of spellings) {
+					regional.add(s)
+				}
+			}
+		}
+
+		if (official.size === 0 && regional.size === 0) continue
+		table[territory] = { official: [...official].sort() }
+
+		if (regional.size > 0) {
+			table[territory]!.regional = [...regional].sort()
+		}
+	}
+
+	const entries = Object.entries(table)
+		.map(([cc, v]) => {
+			const reg = v.regional ? `, regional: [${v.regional.map((l) => `"${l}"`).join(", ")}]` : ""
+
+			return `\t${cc}: { official: [${v.official.map((l) => `"${l}"`).join(", ")}]${reg} },`
+		})
+		.join("\n")
+
+	const header = `/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   GENERATED — do not edit by hand. Official languages per ISO 3166-1 territory, derived from
+ *   Unicode CLDR ${cldrVersion} supplemental territoryInfo (\`_officialStatus\`). \`official\` merges
+ *   CLDR's \`official\` + \`de_facto_official\`; \`regional\` is \`official_regional\` (kept separate —
+ *   the #936 probe showed it pulls in cross-border quirks like Korean-in-CN, so consumers opt in).
+ *   Every language appears under each ISO-639 spelling CLDR aliases to it (fi AND fin) so WOF
+ *   639-3 tags, Overture BCP-47 keys, and GeoNames codes all match without mapping.
+ *   Regenerate with: mailwoman dev generate official-languages
+ */
+
+/** Official-language spellings for one territory. */
+export interface OfficialLanguageEntry {
+	/** CLDR \`official\` + \`de_facto_official\`, in every ISO-639 spelling. */
+	official: readonly string[]
+	/** CLDR \`official_regional\` (e.g. Catalan in ES) — opt-in for consumers. */
+	regional?: readonly string[]
+}
+
+/** ISO 3166-1 alpha-2 → official languages. */
+export const OFFICIAL_LANGUAGES: Record<string, OfficialLanguageEntry> = {
+${entries}
+}
+
+/**
+ * Is \`language\` (any ISO-639 spelling: "sv", "swe", …) an official language of \`country\` (ISO
+ * 3166-1 alpha-2)? Regional-official languages count only with \`includeRegional\`.
+ */
+export function isOfficialLanguage(country: string, language: string, includeRegional = false): boolean {
+	const entry = OFFICIAL_LANGUAGES[country.toUpperCase()]
+
+	if (!entry) return false
+	const lang = language.toLowerCase()
+
+	return entry.official.includes(lang) || (includeRegional && (entry.regional?.includes(lang) ?? false))
+}
+`
+
+	writeFileSync(outPath, header)
+	report?.(`Wrote ${outPath}: ${Object.keys(table).length} territories (CLDR ${cldrVersion})`)
+
+	return { territories: Object.keys(table).length, cldrVersion, outPath }
+}

package/tools/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Codex operator tools — the `run()`-style modules behind `mailwoman dev generate …` commands. No
+ *   argv, no `process.exit`: commands own parsing, rendering, and exit codes (see the 2026-07-09
+ *   scripts→Pastel spec).
+ */
+
+export * from "./generate-country-reference.ts"
+export * from "./generate-official-languages.ts"

package/us/floor-designator.ts

@@ -0,0 +1,119 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   USPS Publication 28, Appendix C2 — Floor-class Secondary Unit Designators.
+ *
+ *   The sibling of {@link ./unit-designator.ts}: where the unit table covers the full secondary-unit
+ *   vocabulary (APT, STE, RM, …), this module extracts the floor-class subset — designators that
+ *   name a FLOOR or LEVEL of the building rather than a specific addressable unit on that floor.
+ *   USPS Pub 28 Appendix C2 identifies these designators as requiring a secondary number: "FL" (the
+ *   approved abbreviation for FLOOR). The publication gives `FLOOR` as the canonical designator
+ *   with approved abbreviation `FL` and variant `FLR`; `BASEMENT` (`BSMT`), `PENTHOUSE` (`PH`), and
+ *   `LOBBY` (`LBBY`) are the standalone-or-numbered floor-adjacent types also listed in Appendix
+ *   C2.
+ *
+ *   Appendix C2 explicitly marks FLOOR, BASEMENT as requiring a secondary number (alongside APT,
+ *   BLDG, etc.) while PENTHOUSE and LOBBY may stand alone. PH and LBBY are kept here (not just in
+ *   {@link ./unit-designator.ts}) because the span proposer treats them as level-class hints —
+ *   "LOBBY" and "PH" name a specific floor-analog, not a numbered unit, and the prior map routes
+ *   `LEVEL_PHRASE` → `unit` (the schema carries no separate `level` tag).
+ *
+ *   This table drives the `levelDesignators` set in the span-proposer lexicon. The full
+ *   secondary-unit designators (APT, STE, RM, …) remain in {@link ./unit-designator.ts}.
+ *
+ *   Data is verbatim USPS Pub 28 Appendix C2.
+ * @see {@link https://pe.usps.com/text/pub28/28apc_003.htm USPS Publication 28 — Appendix C2: Secondary Unit Designators}
+ */
+
+/**
+ * One USPS Pub 28 C2 floor-class designator row.
+ *
+ * `requiresNumber` mirrors the Appendix C2 classification: FLOOR and BASEMENT must be followed by a secondary number;
+ * PENTHOUSE and LOBBY may stand alone.
+ */
+export interface USFloorDesignator {
+	/** Full canonical designator (uppercase per the publication). */
+	name: string
+	/** Approved USPS abbreviation (what the post office prints on standardized mail). */
+	abbreviation: string
+	/** Additional recognized surface variants from Appendix C2. */
+	variants: readonly string[]
+	/**
+	 * True when Appendix C2 marks this designator as "Requires a Secondary Number" (FLOOR, BASEMENT). False for
+	 * standalone types (PENTHOUSE, LOBBY) that name a specific floor-analog without an identifier.
+	 */
+	requiresNumber: boolean
+}
+
+/**
+ * USPS Pub 28 C2 floor-class secondary unit designators. Verbatim from the publication; see the module header for the
+ * per-row provenance. Ordered with the most-common numbered form first.
+ */
+export const US_FLOOR_DESIGNATORS = [
+	{ name: "FLOOR", abbreviation: "FL", variants: ["FLR"], requiresNumber: true },
+	{ name: "BASEMENT", abbreviation: "BSMT", variants: [], requiresNumber: true },
+	{ name: "PENTHOUSE", abbreviation: "PH", variants: [], requiresNumber: false },
+	{ name: "LOBBY", abbreviation: "LBBY", variants: [], requiresNumber: false },
+] as const satisfies readonly USFloorDesignator[]
+
+/** A canonical USPS floor-class designator name. */
+export type USFloorDesignatorName = (typeof US_FLOOR_DESIGNATORS)[number]["name"]
+
+/**
+ * Inverse lookup: every surface form (canonical name, approved abbreviation, or Appendix C2 variant) → its canonical
+ * designator name. Lowercase-keyed for case-insensitive matching: `"fl"` → `"FLOOR"`, `"bsmt"` → `"BASEMENT"`, `"ph"` →
+ * `"PENTHOUSE"`.
+ */
+export const US_FLOOR_DESIGNATOR_LOOKUP: ReadonlyMap<string, USFloorDesignatorName> = (() => {
+	const out = new Map<string, USFloorDesignatorName>()
+
+	for (const row of US_FLOOR_DESIGNATORS) {
+		out.set(row.name.toLowerCase(), row.name)
+		out.set(row.abbreviation.toLowerCase(), row.name)
+
+		for (const v of row.variants) {
+			if (!out.has(v.toLowerCase())) {
+				out.set(v.toLowerCase(), row.name)
+			}
+		}
+	}
+
+	return out
+})()
+
+/**
+ * All lowercase surface tokens for the floor-class designators — the set the span proposer populates `levelDesignators`
+ * with when wiring the US codex slice. Includes canonical names, approved abbreviations, and Appendix C2 variants.
+ */
+export const US_FLOOR_DESIGNATOR_TOKENS: ReadonlySet<string> = new Set(US_FLOOR_DESIGNATOR_LOOKUP.keys())
+
+/** Approved USPS abbreviation per canonical floor designator name. */
+export const US_FLOOR_DESIGNATOR_PREFERRED_ABBR: Readonly<Record<USFloorDesignatorName, string>> = Object.fromEntries(
+	US_FLOOR_DESIGNATORS.map((r) => [r.name, r.abbreviation])
+) as Readonly<Record<USFloorDesignatorName, string>>
+
+/**
+ * Look up a USPS floor-class designator (by canonical name, abbreviation, or any Appendix C2 variant) and return the
+ * canonical name + approved abbreviation. Returns null if the token isn't a recognized floor-class designator.
+ */
+export function lookupFloorDesignator(input: string | null | undefined): {
+	designator: USFloorDesignatorName
+	abbreviation: string
+} | null {
+	if (!input || typeof input !== "string") return null
+	const designator = US_FLOOR_DESIGNATOR_LOOKUP.get(input.trim().toLowerCase())
+
+	if (!designator) return null
+
+	return { designator, abbreviation: US_FLOOR_DESIGNATOR_PREFERRED_ABBR[designator] }
+}
+
+/**
+ * True when a token is a recognized USPS floor-class secondary unit designator (case-insensitive) — `"Floor"`, `"FL"`,
+ * `"flr"`, `"bsmt"`, `"ph"`, `"lbby"`.
+ */
+export function isFloorDesignatorToken(input: unknown): boolean {
+	return typeof input === "string" && US_FLOOR_DESIGNATOR_LOOKUP.has(input.trim().toLowerCase())
+}

package/us/index.ts

@@ -0,0 +1,19 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The United States address system (USPS): street suffixes, secondary unit designators, floor-class
+ *   designators (USPS Pub 28 C2 floor/level subset), military/diplomatic post office designators
+ *   (USPS Pub 28 Chapter 7: APO/FPO/DPO + PSC/CMR/UNIT), ZIP codes, and the state abbreviations
+ *   they hang off of.
+ */
+
+export * from "./floor-designator.ts"
+export * from "./military-address.ts"
+export * from "./po-box.ts"
+export * from "./state.ts"
+export * from "./street-directional.ts"
+export * from "./street-suffix.ts"
+export * from "./unit-designator.ts"
+export * from "./zipcode.ts"