@mailwoman/codex 7.2.0 → 7.3.0

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

@@ -0,0 +1,166 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Build the COUNTRY-SURFACE LEXICON for the country-lexicon soft-feed channel (#1104). This is the
+ *   third atlas channel, a sibling of the postcode anchor (#239/#240) and the gazetteer anchor
+ *   (#464): a per-token multi-hot clue the neural GRAMMAR conditions on but never obeys. Country is a
+ *   CLOSED, ENUMERABLE class (~250 surfaces) — atlas, not grammar — so a dictionary phrase-lookup
+ *   recovers the WOF-admin / resolver hierarchy case ("United States of America, Wyoming, <locality>")
+ *   the learned tagger reads as a leading STREET. Pelias handled the same class the same way
+ *   (`WhosOnFirstClassifier extends PhraseClassifier`); this is the model-first analogue.
+ *
+ *   WHY A DEDICATED LEXICON (not just the gazetteer's `country` slot): the gazetteer already carries
+ *   these surfaces in slot 0, and the shipped model already consumes them — yet the WOF-admin case
+ *   still fails (model-card #1104: golden country recall 82.0% vs 88.6%). The country bit is one of a
+ *   5-hot vector sharing ONE learned projection with region/po_box/cedex/homograph, and it is ZEROED
+ *   adjacent to a postcode by `suppress_gazetteer_near_postcode` (exactly where a trailing "…12345
+ *   USA" sits). A dedicated channel de-entangles the country signal (its own projection + confidence
+ *   weight) and is immune to that suppression. See
+ *   docs/superpowers/plans/2026-07-14-country-lexicon-channel.md.
+ *
+ *   The matcher REUSES the gazetteer's phrase-scan (longest-first n-gram over whitespace words,
+ *   case-insensitive `entries` + uppercase-exact `code_entries`, char→piece projection) — one tested
+ *   algorithm, two vocabularies. Only the vocabulary + the emitted feature differ. The emitted
+ *   feature is 2-dim per piece: `[country_surface, country_ambiguous]`.
+ *
+ *   - `country_surface` (bit 1): the piece is part of a recognized country surface phrase.
+ *   - `country_ambiguous` (bit 2): the SURFACE is a homograph (also a US region) or a common-word
+ *     name ("Georgia", "America", "England", "IN") — a SOFT version of Pelias's hard blacklist. The
+ *     model learns to trust `surface & !ambiguous` (unambiguous long/code forms) strongly and
+ *     `surface & ambiguous` weakly, using context — model-first, never a hard drop, so recall on
+ *     "Republic of Georgia" is preserved.
+ *
+ *   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.
+ *
+ *   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 { COUNTRY_SURFACE_FORMS, ISO2_TO_NAME } from "../country/country.ts"
+import { US_STATE_ABBREVIATIONS, US_STATE_NAMES } from "../us/state.ts"
+
+const BIT = { country_surface: 1, country_ambiguous: 2 }
+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")
+
+/**
+ * THE shared word-normalization rule (identical to build-gazetteer-anchor-lexicon.mjs and mirrored in
+ * gazetteer_char_paint on both sides): per whitespace-word, strip LEADING/TRAILING characters that are not Unicode
+ * letters or digits (keep internal ones: "u.s.a", "timor-leste"), rejoin single-spaced. Entry keys and scanned tokens
+ * both pass through it, so "U.S.A." ≡ "u.s.a".
+ */
+const wordNorm = (s: string): string =>
+	s
+		.split(/\s+/)
+		.map((w) => w.replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, ""))
+		.filter(Boolean)
+		.join(" ")
+
+const norm = (s: string): string => wordNorm(s).toLowerCase()
+
+/** Short alphabetic code (≤3 letters once punctuation is dropped) → exact-uppercase matching. */
+const isShortCode = (s: string): boolean => {
+	const letters = s.replace(/[^\p{L}]/gu, "")
+
+	return letters.length > 0 && letters.length <= 3 && /^[\p{L}.\s]+$/u.test(s)
+}
+
+// Homograph set: a single-word country surface that is ALSO a US region (name or abbreviation) reads
+// ambiguously (Georgia the country vs the state, IN = India vs Indiana). Computed from codex so it
+// tracks the US region table, never hand-maintained.
+const usStateNames = new Set(US_STATE_NAMES.map((n) => n.toLowerCase()))
+const usStateAbbrevs = new Set<string>(US_STATE_ABBREVIATIONS as readonly string[])
+
+// Curated common-word country surfaces — single tokens that appear far more often as ordinary
+// street/venue/locality words than as a trailing country. A SOFT flag (the model still decides), the
+// model-first analogue of Pelias's blacklist (north/south/east/west/street/city/king). Tunable.
+const COMMON_WORD_AMBIGUOUS = new Set(["america", "england", "britain", "turkey", "chad", "jordan", "jersey", "guinea"])
+
+const isAmbiguousName = (lowerKey: string): boolean => usStateNames.has(lowerKey) || COMMON_WORD_AMBIGUOUS.has(lowerKey)
+
+// surface → bits, split across the two match-rule maps (mirrors the gazetteer builder).
+const entries = new Map<string, number>() // lowercase key
+const codeEntries = new Map<string, number>() // exact-uppercase key
+let maxNgram = 1
+
+function add(surface: string): void {
+	const s = surface.trim()
+
+	if (!s) return
+
+	if (isShortCode(s)) {
+		const key = wordNorm(s).toUpperCase()
+
+		if (!key) return
+		// A code that collides with a US-state abbreviation (CA/IN/AL/CO/…) is a homograph → ambiguous.
+		const bits = BIT.country_surface | (usStateAbbrevs.has(key) ? BIT.country_ambiguous : 0)
+		codeEntries.set(key, (codeEntries.get(key) ?? 0) | bits)
+
+		return
+	}
+	const key = norm(s)
+
+	if (!key) return
+	const words = key.split(" ")
+	maxNgram = Math.max(maxNgram, words.length)
+	// Multi-word phrases are unambiguous by construction; single tokens consult the homograph +
+	// common-word rule.
+	const ambiguous = words.length === 1 && isAmbiguousName(key)
+	const bits = BIT.country_surface | (ambiguous ? BIT.country_ambiguous : 0)
+	entries.set(key, (entries.get(key) ?? 0) | bits)
+}
+
+// Curated rich surface forms first (US/GB/DE/… endonyms + abbreviations), then the canonical English
+// name for every remaining ISO 3166-1 alpha-2 — exactly the merge country-surfaces.json performs.
+for (const forms of Object.values(COUNTRY_SURFACE_FORMS)) {
+	for (const f of forms) {
+		add(f)
+	}
+}
+
+for (const [, name] of ISO2_TO_NAME) {
+	add(name)
+}
+
+const ambiguousEntries = [...entries, ...codeEntries].filter(([, b]) => b & BIT.country_ambiguous).map(([k]) => k)
+
+const lexicon = {
+	version: 1,
+	generated_by:
+		"codex/tools/build-country-surface-lexicon.ts (source: @mailwoman/codex COUNTRY_SURFACE_FORMS + ISO2_TO_NAME)",
+	feature_dim: SLOTS.length,
+	slots: SLOTS,
+	bits: BIT,
+	max_ngram: maxNgram,
+	rules: {
+		word_norm:
+			"per whitespace-word: strip leading/trailing chars that are not Unicode letters/digits " +
+			"(keep internal: 'timor-leste', 'u.s.a'); rejoin single-spaced. Applied to BOTH entry keys and scanned tokens.",
+		entries:
+			"case-insensitive; key = word_norm lowercased. country_surface always set; country_ambiguous set for single-token homographs (US region) or curated common-word names.",
+		code_entries:
+			"case-SENSITIVE exact: word_norm(token) == key (keys uppercase; 'in' the word ≠ 'IN' India). n-gram length 1. country_ambiguous set when the code is also a US-state abbreviation.",
+		scan: "longest-first n-gram over whitespace words, left to right, non-overlapping (shared with the gazetteer matcher)",
+		feature:
+			"emitted per-piece row = [country_surface, country_ambiguous] (the raw bits); confidence = 1.0 where country_surface fires.",
+	},
+	entries: Object.fromEntries([...entries].sort(([a], [b]) => a.localeCompare(b))),
+	code_entries: Object.fromEntries([...codeEntries].sort(([a], [b]) => a.localeCompare(b))),
+}
+
+mkdirSync(dirname(OUTPUT), { recursive: true })
+writeFileSync(OUTPUT, JSON.stringify(lexicon, null, 1) + "\n")
+process.stderr.write(
+	`wrote ${OUTPUT}: ${entries.size} entries + ${codeEntries.size} code_entries, ` +
+		`max_ngram=${maxNgram}, ${ambiguousEntries.length} ambiguous: ${ambiguousEntries.slice(0, 12).join(", ")}${ambiguousEntries.length > 12 ? ", …" : ""}\n`
+)

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"