@mailwoman/codex 9.3.0 → 10.0.0

package/lib/address/layouts/index.ts

@@ -0,0 +1,213 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The per-country layout table. Each entry reads in the order it prints, so checking a country means looking at the
+ *   shape of an address from there rather than at a nested call.
+ *
+ *   THE LINE SKELETONS COME FROM libaddressinput, Google's address metadata, which this repository already ships at
+ *   `packages/core/data/chromium-i18n/ssl-address/` (252 countries, Apache-2.0) and already has a refresh command for
+ *   (`mailwoman dev download ssl-address`). Its `fmt` field is the print order — `%N%n%O%n%A%n%C, %S %Z` for the United
+ *   States — and it carries the two things the OpenStreetMap-derived templates get wrong for the locales this project
+ *   publishes weights for: Japan's postal mark and largest-first order, and China's unseparated admin run.
+ *
+ *   WHAT THE DATASET DOES NOT CARRY, and what is therefore authored here:
+ *
+ *   1. **The `%A` expansion.** libaddressinput models the street address as ONE opaque field, because its consumers
+ *      hold it as free text. This project's `ComponentTag` union splits it into a house number, the four street-family
+ *      tags, a unit and the two intersection tags, so each address system says how those fill the line. Six orders
+ *      cover the world: number-first or number-last, crossed with a space, a comma, or a line of its own. Measured
+ *      across the OpenCage templates, 183 of the 211 countries that carry both slots take one of the two space forms.
+ *   2. **The line-join policy.** `%n` is a line break. Rendering it as `", "`, `" "` or `""` for single-line output is
+ *      per-system, and it is the whole difference between a correct Japanese address and a reversed one.
+ *
+ *   3. **The country line.** `%R` is absent from nearly every `fmt`, because libaddressinput's consumers add the
+ *      destination country themselves. It closes a small-first address and opens a large-first one, and it prints only
+ *      when a caller supplies the name — an intra-country row carries none and prints none.
+ *   4. **The post-office box.** The dataset models no box at all; the street node carries it, on its own line directly
+ *      above the street.
+ *
+ *   Adding a country is therefore: transcribe its `fmt` skeleton, pick a street node, and close with the country line.
+ *   A country whose real convention departs from the skeleton says so in place, with its source.
+ */
+
+import {
+	addr,
+	numberFirstCommaStreet,
+	numberFirstStreet,
+	numberLastCommaStreet,
+	numberLastStreet,
+	SLOTS,
+	type AddressLayout,
+} from "#address/layout"
+import { GENERATED_ADDRESS_LAYOUTS } from "#address/layouts/generated"
+
+const { attention, venue, house_number, street, dependent_locality, locality, subregion, region, postcode, country } =
+	SLOTS
+
+/**
+ * The admin run below the prefecture in Japan, printed without separators. Japan's `fmt` carries no `%C` or `%D`, so
+ * everything below the prefecture rides the street-address field.
+ */
+export const japaneseSubPrefecture = addr`${subregion}${locality}${dependent_locality}${house_number}`
+
+/**
+ * China's street line: the name then the number, unseparated, below an admin run its `fmt` prints as `%S%C%D`.
+ */
+export const chineseStreet = addr`${street}${house_number}`
+
+/**
+ * How a system joins its lines for SINGLE-LINE output. Absent reads as `", "`, the anglophone default.
+ *
+ * The CJK entries are the reason this is per-system rather than a caller's argument: joining Japan's lines with a comma
+ * produces `1-9-1, 丸の内, 千代田区, 東京都 100-0005`, which is the romanized convention printed backwards.
+ */
+export const LINE_JOINS: Readonly<Record<string, string>> = {
+	JP: " ",
+	CN: "",
+	TW: "",
+	KR: " ",
+}
+
+/**
+ * Address systems that print the largest unit first.
+ *
+ * It is a property of the system, not of the layout table, so a caller composing its own order — a gazetteer hierarchy
+ * string, say, which is a query rather than an address — reads it here instead of re-deriving it.
+ */
+export const LARGEST_FIRST_SYSTEMS: ReadonlySet<string> = new Set(["JP", "CN", "TW", "KR"])
+
+/**
+ * Whether the country named by `countryCode` prints the largest unit first.
+ */
+export function isLargestFirstSystem(countryCode: string | null | undefined): boolean {
+	if (!countryCode) return false
+
+	return LARGEST_FIRST_SYSTEMS.has(countryCode.trim().toUpperCase())
+}
+
+/**
+ * Per-country layouts for the locales this project publishes weights for.
+ *
+ * Each is the country's libaddressinput `fmt` skeleton with `%A` expanded. The `fmt` is quoted beside it so the two can
+ * be compared without opening the dataset.
+ */
+export const ADDRESS_LAYOUTS: Readonly<Record<string, AddressLayout>> = {
+	// %N%n%O%n%A%n%C, %S %Z
+	US: addr`${attention}
+${venue}
+${numberFirstStreet}
+${locality}, ${region} ${postcode}
+${country}`,
+
+	// %O%n%N%n%A%n%Z %C
+	FR: addr`${venue}
+${attention}
+${numberFirstStreet}
+${dependent_locality}
+${postcode} ${locality}
+${country}`,
+
+	// %N%n%O%n%A%n%C%n%Z
+	GB: addr`${attention}
+${venue}
+${numberFirstStreet}
+${dependent_locality}
+${locality}
+${postcode}
+${country}`,
+
+	// %N%n%O%n%A%n%Z %C
+	DE: addr`${attention}
+${venue}
+${numberLastStreet}
+${dependent_locality}
+${postcode} ${locality}
+${country}`,
+
+	// %N%n%O%n%A%n%Z %C %S — Spain writes the number after a comma: `Calle Mayor, 12`.
+	ES: addr`${attention}
+${venue}
+${numberLastCommaStreet}
+${dependent_locality}
+${postcode} ${locality} ${region}
+${country}`,
+
+	// %N%n%O%n%A%n%Z %C %S
+	IT: addr`${attention}
+${venue}
+${numberLastStreet}
+${dependent_locality}
+${postcode} ${locality} ${region}
+${country}`,
+
+	// %N%n%O%n%A%n%C %Z%n%S — India writes the number before a comma: `12, MG Road`.
+	IN: addr`${attention}
+${venue}
+${numberFirstCommaStreet}
+${dependent_locality}
+${locality} ${postcode}
+${region}
+${country}`,
+
+	// %N%n%O%n%A%n%D%n%C %Z
+	NZ: addr`${attention}
+${venue}
+${numberFirstStreet}
+${dependent_locality}
+${locality} ${postcode}
+${country}`,
+
+	// %O%n%N%n%A%n%C %S %Z
+	AU: addr`${venue}
+${attention}
+${numberFirstStreet}
+${dependent_locality}
+${locality} ${region} ${postcode}
+${country}`,
+
+	// 〒%Z%n%S%n%A%n%O%n%N, with the prefecture joined to the run below it.
+	//
+	// The dataset breaks the line between %S and %A because an envelope prints them on separate lines. Written on ONE
+	// line — which is what a geocoder query and a corpus row are — the whole admin run is unseparated and only the
+	// postal code takes a space: `〒100-0005 東京都千代田区丸の内1-9-1`. Keeping the dataset's break would put a space
+	// after the prefecture, which no Japanese address carries.
+	JP: addr`${country}
+〒${postcode}
+${region}${japaneseSubPrefecture}
+${venue}
+${attention}`,
+
+	// %Z%n%S%C%D%n%A%n%O%n%N — the admin run prints unseparated, which is what `LINE_JOINS.CN` carries.
+	CN: addr`${country}
+${postcode}
+${region}${locality}${dependent_locality}
+${chineseStreet}
+${venue}
+${attention}`,
+}
+
+/**
+ * The layout for `country`, or null when neither table names it.
+ *
+ * The hand-authored entries win: those are checked against real addresses on a board, where a generated skeleton is a
+ * transcription of a dataset. Null is a real answer — 55 of the 252 shipped country records carry no usable `fmt`, and
+ * a caller that renders nothing for one of those is reporting absence rather than inventing an order.
+ */
+export function layoutForCountry(countryCode: string | null | undefined): AddressLayout | null {
+	if (!countryCode) return null
+
+	const code = countryCode.trim().toUpperCase()
+
+	return ADDRESS_LAYOUTS[code] ?? GENERATED_ADDRESS_LAYOUTS[code] ?? null
+}
+
+/**
+ * How the country named by `countryCode` joins its lines for single-line output.
+ */
+export function lineJoinForCountry(countryCode: string | null | undefined): string {
+	if (!countryCode) return ", "
+
+	return LINE_JOINS[countryCode.trim().toUpperCase()] ?? ", "
+}

package/lib/address/render.ts

@@ -0,0 +1,176 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Render a component dict through a per-country layout, keeping the tags.
+ *
+ *   The formatter used to do three things in one function: order the components, join them into a string, and discard
+ *   which tag produced which characters. A caller needing two of the three had to re-implement all three, which is why
+ *   the same `filter(isPresent).join(…)` was hand-written in 28 files and why three corpus modules each hand-wrote
+ *   per-country ordering the templates already encoded.
+ *
+ *   This is the one render. `formatAddress` is the join over it, and the alignment a caller used to recover by
+ *   searching the output string for each value is now a fact the render already holds: {@linkcode AddressRendering}
+ *   says which tags it PLACED and names the ones it could not, where a substring search cannot tell a component the
+ *   layout dropped from one whose value happens to sit inside another.
+ *
+ *   ONE RULE, from `@mailwoman/codex/address-layout`: a node that renders nothing removes itself, and its connector
+ *   goes with it. A connector between two slots needs a rendered slot on each side; a connector at a line's edge has
+ *   one side, so it binds to the slot it touches. Adjacent survivors collapse to the first, so the layout's stronger
+ *   separator wins — an absent region gives `New York, 10118`, which is what the engine this replaces produced.
+ */
+
+import { isAlternation, isConnector, isLayout, isSlot, type AddressAtom, type AddressLayout } from "#address/layout"
+import type { ComponentTag } from "#component"
+
+/**
+ * A partial map of `ComponentTag` → string value — the canonical render input.
+ */
+export type ComponentDict = Partial<Record<ComponentTag, string>>
+
+/**
+ * One rendered piece. `tag` is null for a connector, which is what makes a rendering re-joinable at any separator
+ * without re-deriving which characters were structural.
+ */
+export interface AddressPiece {
+	readonly tag: ComponentTag | null
+	readonly text: string
+}
+
+/**
+ * What a layout did with a dict.
+ */
+export interface AddressRendering {
+	/**
+	 * Every piece in print order, connectors included. Line breaks appear as a piece whose text is `"\n"`.
+	 */
+	readonly pieces: readonly AddressPiece[]
+	/**
+	 * The tags the layout printed.
+	 */
+	readonly placed: readonly ComponentTag[]
+	/**
+	 * Tags the dict carried a value for that the layout has no slot for — NAMED rather than silently dropped. France
+	 * absorbing a region into its postcode line is the common case, and a caller aligning components against the output
+	 * needs to know the difference between "not printed" and "not supplied".
+	 */
+	readonly unplaced: readonly ComponentTag[]
+}
+
+/**
+ * Whether an atom produced any tagged piece, which is what a connector's neighbours are judged on.
+ */
+function rendered(result: readonly AddressPiece[] | null): boolean {
+	return result !== null && result.some((piece) => piece.tag !== null)
+}
+
+function evaluateAtom(atom: AddressAtom, components: ComponentDict): readonly AddressPiece[] | null {
+	if (isSlot(atom)) {
+		const text = components[atom.tag]?.trim()
+
+		return text ? [{ tag: atom.tag, text }] : null
+	}
+
+	if (isAlternation(atom)) {
+		for (const alternative of atom.alternatives) {
+			const pieces = evaluateLines(alternative, components)
+
+			if (pieces.length) return pieces
+		}
+
+		return null
+	}
+
+	if (isLayout(atom)) {
+		const pieces = evaluateLines(atom, components)
+
+		return pieces.length ? pieces : null
+	}
+
+	return null
+}
+
+/**
+ * Which of a run of surviving connectors to print.
+ *
+ * A run forms when the slots between two connectors all render nothing, so what is left is several separators with no
+ * values between them. The STRONGEST wins: a connector carrying punctuation is a harder boundary than a space, and
+ * printing the space would join two values the layout meant to separate. `Calle Mayor, 12` keeps its comma when the
+ * street suffix is absent, and `New York, 10118` keeps its comma when the region is; the space forms of both would read
+ * as one value.
+ */
+function strongestConnector(run: readonly string[]): string {
+	return run.find((text) => /\S/u.test(text)) ?? run[0]!
+}
+
+function evaluateLine(atoms: readonly AddressAtom[], components: ComponentDict): readonly AddressPiece[] {
+	const results = atoms.map((atom) => (isConnector(atom) ? null : evaluateAtom(atom, components)))
+	const out: AddressPiece[] = []
+	let pending: string[] = []
+
+	const flush = (): void => {
+		if (!pending.length) return
+
+		out.push({ tag: null, text: strongestConnector(pending) })
+		pending = []
+	}
+
+	for (const [index, atom] of atoms.entries()) {
+		if (isConnector(atom)) {
+			const left = results.slice(0, index)
+			const right = results.slice(index + 1)
+
+			// A connector at an edge binds to the one slot it touches; between slots it needs one on each side.
+			const survives = !left.length
+				? rendered(results[index + 1] ?? null)
+				: !right.length
+					? rendered(results[index - 1] ?? null)
+					: left.some(rendered) && right.some(rendered)
+
+			if (survives) {
+				pending.push(atom.connector)
+			}
+
+			continue
+		}
+
+		const pieces = results[index]
+
+		if (!pieces) continue
+
+		flush()
+		out.push(...pieces)
+	}
+
+	// Anything still pending trails the last value with nothing after it, so it separates nothing.
+	return out.some((piece) => piece.tag !== null) ? out : []
+}
+
+function evaluateLines(layout: AddressLayout, components: ComponentDict): readonly AddressPiece[] {
+	const lines = layout.lines.map((line) => evaluateLine(line, components)).filter((line) => line.length > 0)
+
+	return lines.flatMap((line, index) => (index > 0 ? [{ tag: null, text: "\n" }, ...line] : line))
+}
+
+/**
+ * Render `components` through `layout`, keeping the tags.
+ */
+export function renderAddress(layout: AddressLayout, components: ComponentDict): AddressRendering {
+	const pieces = evaluateLines(layout, components)
+	const placed = [...new Set(pieces.map((piece) => piece.tag).filter((tag): tag is ComponentTag => tag !== null))]
+	const placedSet = new Set<ComponentTag>(placed)
+
+	const unplaced = (Object.keys(components) as ComponentTag[]).filter(
+		(tag) => Boolean(components[tag]?.trim()) && !placedSet.has(tag)
+	)
+
+	return { pieces, placed, unplaced }
+}
+
+/**
+ * Join a rendering into one string, replacing its line breaks with `separator`.
+ */
+export function joinRendering(rendering: AddressRendering, separator = "\n"): string {
+	return rendering.pieces.map((piece) => (piece.tag === null && piece.text === "\n" ? separator : piece.text)).join("")
+}

package/lib/{address-system-conventions.ts → address/system-conventions.ts}

@@ -18,16 +18,17 @@
  *   by the caller) — an undetected system parses exactly as before.
  */
 
+import type { ComponentTag } from "#component"
 import { CODE_POSTAL_PATTERN } from "#fr/code-postal"
-import { UK_POSTCODE_PATTERN } from "#gb/postcode"
-import type { SystemCode } from "#postcode-systems"
+import { UK_POSTCODE_PATTERN } from "#gb/postcode/index"
+import type { SystemCode } from "#postcode/systems"
 
 export interface AddressSystemConventions {
 	/**
-	 * Component tags that are NOT grammatical in this address system (names from the core `ComponentTag` union; codex
-	 * stays dependency-free so they are plain strings here).
+	 * Component tags that are NOT grammatical in this address system. Typed against the union itself, so a tag that no
+	 * longer exists is a compile error here rather than a rule that silently forbids nothing.
 	 */
-	readonly forbiddenTags?: readonly string[]
+	readonly forbiddenTags?: readonly ComponentTag[]
 	/**
 	 * The system's canonical postcode shape. A decoded postcode span that is a strict sub-match of a pattern-valid string
 	 * in the raw text is shape-INVALID for this system and eligible for the snap-only repair (extend/clip to the valid

package/lib/component.ts

@@ -0,0 +1,96 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Canonical address component schema for the neural classifier pipeline.
+ *
+ *   This file is the single source of truth for `ComponentTag`. Any change here requires (per #5 of
+ *   the Mailwoman Neural plan):
+ *
+ *   1. A written rationale in the commit message.
+ *   2. A migration plan for corpus rows tagged with the prior schema.
+ *   3. A same-commit check that alignment, training, and inference code is updated to match.
+ *
+ *   The legacy `Classifications` set in `../classification/scheme.ts` is kept independent on purpose:
+ *   rule classifiers continue to emit those, the neural classifier emits these. The bridge between
+ *   the two lives in the adapter layer (see #6).
+ */
+
+/**
+ * The canonical address component tag union, ordered by phase and locale.
+ *
+ * - Universal (Phase 1): country, region, locality, dependent_locality, postcode, subregion
+ * - Street-level (Phase 2): house_number, street, street_prefix*, street_suffix, intersection_a/b, unit
+ * - Venue-level (Phase 3): venue, attention, po_box
+ * - FR-specific: cedex
+ * - JP-specific (ACTIVATED at CJK Phase 2, 2026-07-29 — the JP char model's 47-label head trains against them; the Latin
+ *   model never emits them): prefecture, municipality, district, block, sub_block, building_number, building_name
+ */
+export const COMPONENT_TAGS = [
+	// Universal
+	"country",
+	"region",
+	"locality",
+	"dependent_locality",
+	"postcode",
+	"subregion",
+	// Street-level
+	"house_number",
+	"street",
+	"street_prefix",
+	"street_prefix_particle",
+	"street_suffix",
+	"intersection_a",
+	"intersection_b",
+	"unit",
+	// Venue-level
+	"venue",
+	"attention",
+	"po_box",
+	// FR-specific
+	"cedex",
+	// JP-specific (ACTIVATED at CJK Phase 2 — the stage3-jp label set; Latin models never emit these)
+	"prefecture",
+	"municipality",
+	"district",
+	"block",
+	"sub_block",
+	"building_number",
+	"building_name",
+	// CN-specific (#2034): the organizational ladder China's rural addresses carry below the named settlement —
+	// state-farm sub-farms (分场), production brigades and teams (大队, 队, 生产队), XPCC regiments and companies (团, 连),
+	// villager groups (组). ONE contiguous span holds the whole ordinal chain (`三分场八队`); which rung each generic names
+	// is a deterministic reading of the suffix, not a label distinction, so the tag stays one and the split is derived.
+	// The named head unit (`孟定农场`, `新合`) is `dependent_locality`. Emitted by the CJK sibling model only.
+	"locality_unit",
+] as const
+
+/**
+ * Union of every recognized address component tag.
+ */
+export type ComponentTag = (typeof COMPONENT_TAGS)[number]
+
+/**
+ * BIO-encoded label set: one `O` plus a `B-` / `I-` pair per tag.
+ *
+ * Used as the per-token output alphabet for the sequence-labeling neural model. Inference decodes a stream of these
+ * back into character-aligned `ClassificationProposal`s.
+ */
+export const BIO_LABELS = ["O", ...COMPONENT_TAGS.flatMap((tag) => [`B-${tag}`, `I-${tag}`] as const)] as const
+
+/**
+ * Union of every BIO label.
+ */
+export type BIOLabel = (typeof BIO_LABELS)[number]
+
+/**
+ * The street-name family in assembly order: prefix, particle, name, suffix. The order is part of the contract — a
+ * street surface is assembled by concatenating these tags' values in this order.
+ */
+export const STREET_FAMILY_TAGS = [
+	"street_prefix",
+	"street_prefix_particle",
+	"street",
+	"street_suffix",
+] as const satisfies readonly ComponentTag[]

package/lib/country/index.ts

@@ -12,6 +12,7 @@ export * from "#country/display-names"
 export * from "#country/names"
 export * from "#country/official-languages"
 export * from "#country/population"
-export * from "#country/reference-data"
-export * from "#country/reference"
+export * from "#country/reference/data"
+export * from "#country/reference/index"
+export * from "#country/region-languages"
 export * from "#country/subdivision"

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

@@ -11,7 +11,7 @@
 
 import type { AnnotationSet, Annotator } from "@mailwoman/annotations"
 
-import { COUNTRY_REFERENCE } from "#country/reference-data"
+import { COUNTRY_REFERENCE } from "#country/reference/data"
 
 const REGIONAL_INDICATOR_BASE = 0x1_f1_e6
 const A_UPPER = "A".charCodeAt(0)

package/lib/country/region-languages.ts

@@ -0,0 +1,46 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The languages a REGION's addresses are written in: the country's official languages plus the region's own
+ *   co-official ones, in ISO 639-3 (the code the Who's On First names table carries). This is the question a corpus
+ *   extraction asks when it turns a region record into the surfaces a person types, and it differs from
+ *   {@link isOfficialLanguage} in two ways: it answers per region rather than per country, and it refuses the
+ *   country-wide `regional` list, whose languages are official somewhere in the country and not in the region at hand.
+ *
+ *   Spain is the one country with a per-region table so far; every other country answers with its official languages
+ *   alone, which for GB, FR, DE, IT, NL and PT is the language the source addresses are already written in.
+ */
+
+import { OFFICIAL_LANGUAGES } from "#country/official-languages"
+import { coOfficialLanguagesForProvince } from "#es/co-official-languages"
+
+/**
+ * The length of an ISO 639-3 code, the spelling the Who's On First names table uses; the generated table lists each
+ * language under its ISO 639-1 spelling too, which is two letters.
+ */
+const ALPHA3_LENGTH = 3
+
+function isAlpha3(code: string): boolean {
+	return code.length === ALPHA3_LENGTH
+}
+
+/**
+ * The country's official languages in ISO 639-3, or empty for an unknown country.
+ */
+export function officialLanguagesAlpha3(country: string): readonly string[] {
+	return (OFFICIAL_LANGUAGES[country.toUpperCase()]?.official ?? []).filter(isAlpha3)
+}
+
+/**
+ * The languages a region's addresses are written in: the country's official languages first, then the region's
+ * co-official ones. `regionOfficialName` is the region's name in the country's first official language, the key the
+ * per-country tables use.
+ */
+export function regionLanguagesAlpha3(country: string, regionOfficialName: string): readonly string[] {
+	const official = officialLanguagesAlpha3(country)
+	const coOfficial = country.toUpperCase() === "ES" ? coOfficialLanguagesForProvince(regionOfficialName) : []
+
+	return [...official, ...coOfficial.filter((code) => !official.includes(code))]
+}

package/lib/es/co-official-languages.ts

@@ -0,0 +1,62 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Spain's co-official languages by province — the languages a person in that province writes an address in beside
+ *   Castilian. The Constitution (art. 3.2) makes each community's Statute of Autonomy the instrument that declares a
+ *   co-official language, so the table follows the statutes:
+ *
+ *   - Catalan (`cat`): the Statute of Catalonia (2006, art. 6) for Barcelona, Girona, Lleida and Tarragona; the Statute
+ *     of the Balearic Islands (2007, art. 4); and the Statute of the Valencian Community (2006, art. 6) for Alicante,
+ *     Castellón and Valencia, whose Valencian the Who's On First names table files under `cat`.
+ *   - Occitan (`oci`, Aranese): the Statute of Catalonia (2006, art. 6.5) makes it official throughout Catalonia.
+ *   - Galician (`glg`): the Statute of Galicia (1981, art. 5) for A Coruña, Lugo, Ourense and Pontevedra.
+ *   - Basque (`eus`): the Statute of the Basque Country (1979, art. 6) for Álava, Biscay and Gipuzkoa; the Foral Law
+ *     18/1986 of Navarre for its Basque-speaking zone.
+ *
+ *   Asturian and Aragonese are protected by their statutes and not co-official, so Asturias, Huesca, Teruel and Zaragoza
+ *   carry no entry. Ceuta, Melilla and the province-less territories carry none.
+ *
+ *   WHY A TABLE AND NOT THE GAZETTEER. Who's On First stores a preferred name for a province in many languages, and for
+ *   a language not spoken there the "preferred name" is often the AUTONOMOUS COMMUNITY's: Zamora's Catalan preferred
+ *   name is `Castella i Lleó`, Seville's Asturian one is `Andalucía`, Ourense's Occitan one is `Galícia`. Reading every
+ *   language's name as a surface of the province would teach those pairs. The statute says which languages a province's
+ *   addresses are written in; this table carries that answer, keyed by the province's Castilian name as the gazetteer
+ *   spells it in its `spa` preferred form.
+ */
+
+/**
+ * ISO 639-3 codes of the co-official languages of each Spanish province that has one, keyed by the province's Castilian
+ * name (the `spa` preferred name in the Who's On First names table).
+ */
+export const ES_PROVINCE_CO_OFFICIAL_LANGUAGES: ReadonlyMap<string, readonly string[]> = new Map([
+	// Catalonia: Catalan and Aranese Occitan (Statute of Catalonia 2006, art. 6).
+	["Barcelona", ["cat", "oci"]],
+	["Girona", ["cat", "oci"]],
+	["Lleida", ["cat", "oci"]],
+	["Tarragona", ["cat", "oci"]],
+	// Balearic Islands: Catalan (Statute 2007, art. 4).
+	["Islas Baleares", ["cat"]],
+	// Valencian Community: Valencian, filed as `cat` (Statute 2006, art. 6).
+	["Alicante", ["cat"]],
+	["Castellón", ["cat"]],
+	["Valencia", ["cat"]],
+	// Galicia: Galician (Statute 1981, art. 5).
+	["La Coruña", ["glg"]],
+	["Lugo", ["glg"]],
+	["Orense", ["glg"]],
+	["Pontevedra", ["glg"]],
+	// Basque Country: Basque (Statute 1979, art. 6); Navarre: Basque in its Basque-speaking zone (Foral Law 18/1986).
+	["Álava", ["eus"]],
+	["Vizcaya", ["eus"]],
+	["Guipúzcoa", ["eus"]],
+	["Navarra", ["eus"]],
+])
+
+/**
+ * The co-official languages of a Spanish province, by its Castilian name; empty for a province with none.
+ */
+export function coOfficialLanguagesForProvince(castilianName: string): readonly string[] {
+	return ES_PROVINCE_CO_OFFICIAL_LANGUAGES.get(castilianName.trim()) ?? []
+}

package/lib/es/index.ts

@@ -6,4 +6,5 @@
  *   Spanish (ES) address-system reference data.
  */
 
+export * from "#es/co-official-languages"
 export * from "#es/codigo-postal"

package/lib/gb/index.ts

@@ -9,6 +9,6 @@
  */
 
 export * from "#gb/country"
-export * from "#gb/postcode-area"
-export * from "#gb/postcode"
+export * from "#gb/postcode/area"
+export * from "#gb/postcode/index"
 export * from "#gb/street-type"

package/lib/index.ts

@@ -25,9 +25,11 @@ export {
 	ADDRESS_SYSTEM_CONVENTIONS,
 	conventionsForSystem,
 	type AddressSystemConventions,
-} from "#address-system-conventions"
+} from "#address/system-conventions"
 
+export * from "#component"
 export * from "#normalize"
+export * from "#placetype-map"
 export * as au from "#au/index"
 export * as ca from "#ca/index"
 export * as de from "#de/index"
@@ -45,6 +47,6 @@ export {
 	SYSTEM_CODES,
 	type SystemCode,
 	UNIT_GRADE_POSTCODE,
-} from "#postcode-systems"
+} from "#postcode/systems"
 
 export * as us from "#us/index"