@mailwoman/corpus 9.3.0 → 10.0.0

package/README.md

@@ -27,6 +27,7 @@ The corpus pipeline assembles training data from multiple sources:
 | **libpostal**      | Multilingual street/place name dictionaries                              |
 | **Synthetic rows** | Generated address variations (boundary stress, order variants, all-caps) |
 | **Overture Maps**  | Address theme ingestion (alpha)                                          |
+| **OpenStreetMap**  | Pakistan, Bangladesh, Vietnam — ODbL, dropped by `--exclude-share-alike` |
 
 Output format: TSV rows with `raw<TAB>BIO_labels` consumed by the Python
 training pipeline (`corpus-python/`).
@@ -43,6 +44,21 @@ training pipeline (`corpus-python/`).
 | **`slice-registry.ts`** | Subset metadata and composition                                  |
 | **`stats.ts`**          | Per-subset and per-tag statistics                                |
 
+## Layout
+
+The top-level ownership boundary is the address system, using ISO 3166-1 alpha-2 country
+directories. A directory owns its recipes, source adapters, acquisition tools, and tests together:
+`fr/{recipes,adapters,tools}`, `kr/{adapters,tools}`, and
+`us/{adapters,tools}` are representative. Regional and global work lives under `south-asia/` and
+`international/`; cross-locale primitives remain at the `recipes/` and `synthesizers/` roots.
+
+Sources that deliberately span countries (OpenAddresses, GeoNames, Overture, OSM, and WOF) remain
+under `adapters/`, with their common fetching and processing utilities under `tools/`. Source kind
+is therefore a nested concern inside a country directory, not the package's organizing principle.
+Tests live beside the module they cover: `fr/adapters/ban/adapter.test.ts` belongs with
+`fr/adapters/ban/adapter.ts`. Production compilation excludes `*.test.ts`; the test project includes
+the same pattern. Public subpaths use this same locale-first layout.
+
 ## Build-time tooling
 
 The corpus is assembled via scripts in `scripts/`:

package/lib/adapters/geonames/adapter.ts

@@ -22,14 +22,14 @@
  *   balance so the model sees both domestic and international order) —
  *
  *   1. `{ locality, region }` → "City, Region"
- *   2. `{ locality, region, country }` → "City, Region, Country" `reconcileComponents` drops any
+ *   2. `{ locality, region, country }` → "City, Region, Country" `componentsPresentIn` drops any
  *        component that didn't survive into the rendered `raw`.
  *
  *   License: stamped `"CC-BY-4.0"` per row (GeoNames' terms); provenance is the `geonames-<id>` key.
  */
 
+import { componentsPresentIn } from "@mailwoman/codex/address-format"
 import { pathExists } from "@mailwoman/core/fs/readers"
-import { reconcileComponents } from "@mailwoman/formatter"
 import { dirname, join } from "path-ts"
 import { TSVSpliterator } from "spliterator"
 
@@ -168,7 +168,7 @@ export function createGeonamesAdapter(): CorpusAdapter {
 
 				for (const v of variants) {
 					if (opts.limit !== undefined && emitted >= opts.limit) break
-					const aligned = reconcileComponents(v.comp, v.raw)
+					const aligned = componentsPresentIn(v.comp, v.raw)
 
 					if (!Object.keys(aligned).length) continue
 

package/lib/adapters/geonames/postal/adapter.ts

@@ -0,0 +1,122 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `geonames-postal`: GeoNames postal-code dump consumer (https://www.geonames.org/, CC-BY-4.0).
+ *
+ *   The GeoNames postal export (`https://download.geonames.org/export/zip/<CC>.zip`) is a clean,
+ *   per-country `postcode → place → admin1` table with the place + region NAMES inline (no aux-file
+ *   join needed). It broadens the corpus's postcode→locality→region coverage to ~80 countries, well
+ *   beyond `wof-postalcode`/the coordinate-first table — forward coverage for the multi-locale
+ *   goal.
+ *
+ *   Input: a per-country postal dump (`<CC>.txt`, 12 tab-separated columns, no header): country,
+ *   postcode, place, admin1_name, admin1_code, admin2__, admin3__, lat, lon, accuracy.
+ *
+ *   Output: per row, postcode-FIRST (international) variants — the common order for the non-US
+ *   locales this fills (US postcodes are already covered by TIGER/WOF, which use postcode-LAST):
+ *
+ *   1. `{ postcode, locality }` → "AD100 Canillo"
+ *   2. `{ postcode, locality, region }` → "AD100 Canillo, Canillo" Prefer configuring this adapter for
+ *        non-US countries; for US, the postcode-last sources are the right order. License:
+ *        `"CC-BY-4.0"` per row (attribute "GeoNames").
+ */
+
+import { componentsPresentIn } from "@mailwoman/codex/address-format"
+import { TSVSpliterator } from "spliterator"
+
+import { stableSourceID } from "#adapters/utils"
+import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "#types"
+
+/**
+ * Registry id for this adapter. Stamped into every row it emits, so a corpus record can be traced back to the dataset
+ * it came from.
+ */
+export const GEONAMES_POSTAL_ADAPTER_ID = "geonames-postal"
+/**
+ * License carried by this source (CC-BY-4.0), attached to each row so downstream consumers inherit the terms rather
+ * than having to look them up.
+ */
+export const GEONAMES_POSTAL_DEFAULT_LICENSE = "CC-BY-4.0"
+
+/**
+ * GeoNames postal-dump columns (0-based): country, postcode, place, admin1_name, admin1_code, admin2_name, ….
+ *
+ * Shared with `tools/postcode-triples.ts`, which additionally reads `admin2Name` — the CITY for the IN/MX/PT-shaped
+ * exports whose `place` column is a street or colonia.
+ */
+export const GEONAMES_POSTAL_COLUMNS = { country: 0, postcode: 1, place: 2, admin1Name: 3, admin2Name: 5 } as const
+
+export function createGeonamesPostalAdapter(): CorpusAdapter {
+	return {
+		id: GEONAMES_POSTAL_ADAPTER_ID,
+		defaultLicense: GEONAMES_POSTAL_DEFAULT_LICENSE,
+		description:
+			"GeoNames postcodes (CC-BY-4.0) — multi-locale postcode→locality→region, names inline; international postcode-first order.",
+
+		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
+			// `header: false` — the GeoNames postal dump is headerless, and the spliterator would
+			// otherwise consume row 1 as column names and lose its first postcode.
+			const rows = TSVSpliterator.fromAsync(opts.inputPath, { header: false })
+
+			let emitted = 0
+
+			for await (const rec of rows as AsyncIterable<string[]>) {
+				if (opts.signal?.aborted) break
+
+				if (opts.limit !== undefined && emitted >= opts.limit) break
+
+				const cc = (rec[GEONAMES_POSTAL_COLUMNS.country] ?? "").trim()
+
+				if (!cc) continue
+
+				if (opts.country && cc !== opts.country) continue
+
+				const postcode = (rec[GEONAMES_POSTAL_COLUMNS.postcode] ?? "").trim()
+				const locality = (rec[GEONAMES_POSTAL_COLUMNS.place] ?? "").trim()
+
+				if (!postcode || !locality) continue
+				const region = (rec[GEONAMES_POSTAL_COLUMNS.admin1Name] ?? "").trim()
+
+				// Postcode-first (international) variants. Skip the region variant when admin1 just
+				// repeats the place (common for city-states / micro-admin) to avoid "X X" noise.
+				const variants: Array<{ slot: string; comp: CanonicalRow["components"]; raw: string }> = [
+					{ slot: "pl", comp: { postcode, locality }, raw: `${postcode} ${locality}` },
+				]
+
+				if (region && region.toLowerCase() !== locality.toLowerCase()) {
+					variants.push({
+						slot: "plr",
+						comp: { postcode, locality, region },
+						raw: `${postcode} ${locality}, ${region}`,
+					})
+				}
+
+				for (const v of variants) {
+					if (opts.limit !== undefined && emitted >= opts.limit) break
+					const aligned = componentsPresentIn(v.comp, v.raw)
+
+					if (Object.keys(aligned).length < 2) continue
+
+					yield {
+						raw: v.raw,
+						components: aligned,
+						country: cc,
+						source: GEONAMES_POSTAL_ADAPTER_ID,
+						source_id: `${stableSourceID(GEONAMES_POSTAL_ADAPTER_ID, aligned)}-${v.slot}`,
+						corpus_version: "",
+						license: GEONAMES_POSTAL_DEFAULT_LICENSE,
+					}
+
+					emitted++
+				}
+			}
+		},
+	}
+}
+
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const geonamesPostalAdapter = createGeonamesPostalAdapter()

package/lib/adapters/index.ts

@@ -19,27 +19,28 @@
  *   implementations; the registered ids are unchanged).
  */
 
-import { banAdapter } from "#adapters/ban/adapter"
-import { fccBdcAdapter } from "#adapters/fcc-bdc/adapter"
-import { geonamesPostalAdapter } from "#adapters/geonames-postal/adapter"
 import { geonamesAdapter } from "#adapters/geonames/adapter"
-import { gnafAdapter } from "#adapters/gnaf/adapter"
+import { geonamesPostalAdapter } from "#adapters/geonames/postal/adapter"
 import { openaddressesAdapter } from "#adapters/openaddresses/adapter"
+import { osmAdapter } from "#adapters/osm/adapter"
 import { overtureAdapter } from "#adapters/overture/adapter"
-import { stateHiSchoolsAdapter } from "#adapters/state-hi-schools/adapter"
-import { stateIaContractorsAdapter } from "#adapters/state-ia-contractors/adapter"
-import { stateNyNotariesAdapter } from "#adapters/state-ny-notaries/adapter"
-import { stateTxNotariesAdapter } from "#adapters/state-tx-notaries/adapter"
-import { tigerAdapter } from "#adapters/tiger/adapter"
-import { usgovHrsaFqhcAdapter } from "#adapters/usgov-hrsa-fqhc/adapter"
-import { usgovImlsPlsAdapter } from "#adapters/usgov-imls-pls/adapter"
-import { USGovIRSBMFAdapter } from "#adapters/usgov-irs-bmf/adapter"
-import { usgovNADAdapter } from "#adapters/usgov-nad/adapter"
-import { usgovNPPESAdapter } from "#adapters/usgov-nppes/adapter"
 import { defaultAdapterRegistry } from "#adapters/utils"
-import { wofAdminAdapter } from "#adapters/wof-admin-json/adapter"
-import { wofPostalcodeAdapter } from "#adapters/wof-postalcode-json/adapter"
+import { wofAdminAdapter } from "#adapters/wof/admin/json/adapter"
+import { wofPostalcodeAdapter } from "#adapters/wof/postalcode-json/adapter"
+import { gnafAdapter } from "#au/adapters/gnaf/adapter"
+import { banAdapter } from "#fr/adapters/ban/adapter"
 import type { CorpusAdapter } from "#types"
+import { fccBdcAdapter } from "#us/adapters/fcc-bdc/adapter"
+import { stateHiSchoolsAdapter } from "#us/adapters/state/hi-schools/adapter"
+import { stateIaContractorsAdapter } from "#us/adapters/state/ia-contractors/adapter"
+import { stateNyNotariesAdapter } from "#us/adapters/state/ny-notaries/adapter"
+import { stateTxNotariesAdapter } from "#us/adapters/state/tx-notaries/adapter"
+import { tigerAdapter } from "#us/adapters/tiger/adapter"
+import { usgovHrsaFqhcAdapter } from "#us/adapters/usgov/hrsa-fqhc/adapter"
+import { usgovImlsPlsAdapter } from "#us/adapters/usgov/imls-pls/adapter"
+import { USGovIRSBMFAdapter } from "#us/adapters/usgov/irs-bmf/adapter"
+import { usgovNADAdapter } from "#us/adapters/usgov/nad/adapter"
+import { usgovNPPESAdapter } from "#us/adapters/usgov/nppes/adapter"
 
 /**
  * Built-in adapters. Order is significant: `corpus build` iterates this list to drive every adapter in turn.
@@ -60,6 +61,7 @@ export const BUILTIN_ADAPTERS: readonly CorpusAdapter[] = [
 	tigerAdapter,
 	openaddressesAdapter,
 	overtureAdapter,
+	osmAdapter,
 	gnafAdapter,
 	fccBdcAdapter,
 	usgovHrsaFqhcAdapter,
@@ -79,14 +81,14 @@ for (const adapter of BUILTIN_ADAPTERS) {
 	}
 }
 
-export { BAN_ADAPTER_ID, banAdapter } from "#adapters/ban/adapter"
-export { FCC_BDC_ADAPTER_ID, FCC_BDC_DEFAULT_LICENSE, fccBdcAdapter } from "#adapters/fcc-bdc/adapter"
+export { BAN_ADAPTER_ID, banAdapter } from "#fr/adapters/ban/adapter"
+export { FCC_BDC_ADAPTER_ID, FCC_BDC_DEFAULT_LICENSE, fccBdcAdapter } from "#us/adapters/fcc-bdc/adapter"
 
 export {
 	GEONAMES_POSTAL_ADAPTER_ID,
 	GEONAMES_POSTAL_DEFAULT_LICENSE,
 	geonamesPostalAdapter,
-} from "#adapters/geonames-postal/adapter"
+} from "#adapters/geonames/postal/adapter"
 
 export { GEONAMES_ADAPTER_ID, GEONAMES_DEFAULT_LICENSE, geonamesAdapter } from "#adapters/geonames/adapter"
 
@@ -100,54 +102,59 @@ export {
 	STATE_HI_SCHOOLS_ADAPTER_ID,
 	STATE_HI_SCHOOLS_DEFAULT_LICENSE,
 	stateHiSchoolsAdapter,
-} from "#adapters/state-hi-schools/adapter"
+} from "#us/adapters/state/hi-schools/adapter"
 
 export {
 	STATE_IA_CONTRACTORS_ADAPTER_ID,
 	STATE_IA_CONTRACTORS_DEFAULT_LICENSE,
 	stateIaContractorsAdapter,
-} from "#adapters/state-ia-contractors/adapter"
+} from "#us/adapters/state/ia-contractors/adapter"
 
 export {
 	STATE_NY_NOTARIES_ADAPTER_ID,
 	STATE_NY_NOTARIES_DEFAULT_LICENSE,
 	stateNyNotariesAdapter,
-} from "#adapters/state-ny-notaries/adapter"
+} from "#us/adapters/state/ny-notaries/adapter"
 
 export {
 	STATE_TX_NOTARIES_ADAPTER_ID,
 	STATE_TX_NOTARIES_DEFAULT_LICENSE,
 	stateTxNotariesAdapter,
-} from "#adapters/state-tx-notaries/adapter"
+} from "#us/adapters/state/tx-notaries/adapter"
 
-export { TIGER_ADAPTER_ID, TIGER_DEFAULT_LICENSE, tigerAdapter } from "#adapters/tiger/adapter"
+export { TIGER_ADAPTER_ID, TIGER_DEFAULT_LICENSE, tigerAdapter } from "#us/adapters/tiger/adapter"
 
 export {
 	USGOV_HRSA_FQHC_ADAPTER_ID,
 	USGOV_HRSA_FQHC_DEFAULT_LICENSE,
 	usgovHrsaFqhcAdapter,
-} from "#adapters/usgov-hrsa-fqhc/adapter"
+} from "#us/adapters/usgov/hrsa-fqhc/adapter"
 
 export {
 	USGOV_IMLS_PLS_ADAPTER_ID,
 	USGOV_IMLS_PLS_DEFAULT_LICENSE,
 	usgovImlsPlsAdapter,
-} from "#adapters/usgov-imls-pls/adapter"
+} from "#us/adapters/usgov/imls-pls/adapter"
 
 export {
 	USGOV_IRS_BMF_ADAPTER_ID,
 	USGOV_IRS_BMF_DEFAULT_LICENSE,
 	USGovIRSBMFAdapter,
-} from "#adapters/usgov-irs-bmf/adapter"
+} from "#us/adapters/usgov/irs-bmf/adapter"
 
-export { USGOV_NAD_ADAPTER_ID, USGOV_NAD_DEFAULT_LICENSE, usgovNADAdapter } from "#adapters/usgov-nad/adapter"
-export { USGOV_NPPES_ADAPTER_ID, USGOV_NPPES_DEFAULT_LICENSE, usgovNPPESAdapter } from "#adapters/usgov-nppes/adapter"
+export { USGOV_NAD_ADAPTER_ID, USGOV_NAD_DEFAULT_LICENSE, usgovNADAdapter } from "#us/adapters/usgov/nad/adapter"
+
+export {
+	USGOV_NPPES_ADAPTER_ID,
+	USGOV_NPPES_DEFAULT_LICENSE,
+	usgovNPPESAdapter,
+} from "#us/adapters/usgov/nppes/adapter"
 
 export {
 	USGOV_SAMHSA_ADAPTER_ID,
 	USGOV_SAMHSA_DEFAULT_LICENSE,
 	usgovSamhsaTreatmentLocatorAdapter,
-} from "#adapters/usgov-samhsa-treatment-locator/adapter"
+} from "#us/adapters/usgov/samhsa-treatment-locator/adapter"
 
-export { WOF_ADMIN_ADAPTER_ID, wofAdminAdapter } from "#adapters/wof-admin-json/adapter"
-export { WOF_POSTALCODE_ADAPTER_ID, wofPostalcodeAdapter } from "#adapters/wof-postalcode-json/adapter"
+export { WOF_ADMIN_ADAPTER_ID, wofAdminAdapter } from "#adapters/wof/admin/json/adapter"
+export { WOF_POSTALCODE_ADAPTER_ID, wofPostalcodeAdapter } from "#adapters/wof/postalcode-json/adapter"

package/lib/adapters/openaddresses/adapter.ts

@@ -36,8 +36,8 @@
  *   for non-US locales where district names DO appear on the envelope.
  */
 
+import { formatAddressRow } from "@mailwoman/codex/address-format"
 import { tryParsingJSON } from "@mailwoman/core/json"
-import { formatAddress, reconcileComponents } from "@mailwoman/formatter"
 import { TextSpliterator } from "spliterator"
 
 import { stableSourceID } from "#adapters/utils"
@@ -210,14 +210,11 @@ export function createOpenaddressesAdapter(opts: OpenaddressesAdapterOptions = {
 						components.postcode = postcode
 					}
 
-					const raw = formatAddress(components, country, { separator: ", " })
+					const rendered = formatAddressRow(components, country, { singleLine: true })
 
-					if (!raw) continue
-
-					const aligned = reconcileComponents(components, raw)
-
-					if (!Object.keys(aligned).length) continue
+					if (!rendered) continue
 
+					const { raw, components: aligned } = rendered
 					const sourceIDSeed = props.hash?.trim() || props.id?.trim()
 
 					const sourceID = sourceIDSeed

package/lib/adapters/osm/adapter.ts

@@ -0,0 +1,278 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `osm`: OpenStreetMap address adapter (#733) for the countries no permissive source covers. Overture's addresses
+ *   theme has no rows for Pakistan, Bangladesh or Vietnam (the three parquets are 532-byte headers), and the Latin
+ *   model has never seen their formats: the Islamabad sector line, the Dhaka trailing postcode, the `Đường`-led street.
+ *
+ *   This adapter consumes the per-country JSONL `@mailwoman/osm`'s `emit-corpus-jsonl` script writes from a Geofabrik
+ *   extract (`{ street, number, postcode?, suburb?, city?, unit?, place?, subdistrict?, district?, province?, lat, lon
+ *   }`), the same split the `overture` adapter rides so the corpus package never meets GDAL or a PBF.
+ *
+ *   ⚠ ODbL. Every row carries `license: "ODbL-1.0"`, which `SHARE_ALIKE_PATTERN` matches: a proprietary-weights build
+ *   passes `--exclude-share-alike` and drops these rows at ingest, so they reach the open weights only. That is the
+ *   whole licensing contract of this adapter, and the reason `defaultLicense` is not an option.
+ *
+ *   The mapping keeps to what a person types on the envelope. Mappers put free text in `addr:housenumber` (`House 34,
+ *   Road 4, Sector 9`, `Near Askari Towers 2`) and in `addr:street`; a house number is kept only in a designator shape,
+ *   and a street with a comma or more than eight words is skipped as a line rather than a name. `addr:city` in
+ *   Bangladesh often carries the neighborhood too (`Mirpur 10, Dhaka`): the last comma-separated part is the locality
+ *   and the head becomes the dependent locality when no `addr:suburb` names one. `addr:district` is NOT mapped on its
+ *   own: for Vietnam it is the quận below the city, which the country template renders only when no city is present,
+ *   so a mapped district with a city would be a component with no span to align to and the row would quarantine.
+ *
+ *   | JSONL field                                | ComponentTag                                              |
+ *   | ------------------------------------------ | --------------------------------------------------------- |
+ *   | `number`                                   | `house_number` when designator-shaped (`12`, `14/E`, `B-77`) |
+ *   | `street`                                   | `street` (keyword included; affix-relabel splits it)      |
+ *   | `unit`                                     | `unit`                                                     |
+ *   | `postcode`                                 | `postcode` when 4–6 digits                                 |
+ *   | `city` (tail after the last comma)         | `locality`                                                 |
+ *   | `suburb` ?? `subdistrict` ?? `district` ?? `place` ?? city head | `dependent_locality`                          |
+ *   | `province`                                 | `region`, unless it repeats the locality                   |
+ */
+
+import { formatAddressRow } from "@mailwoman/codex/address-format"
+import { tryParsingJSON } from "@mailwoman/core/json"
+import { stripCombiningMarks } from "@mailwoman/normalize/fold"
+import { TextSpliterator } from "spliterator"
+
+import { stableSourceID } from "#adapters/utils"
+import type { AdapterOptions, CanonicalRow, CorpusAdapter } from "#types"
+
+/**
+ * Registry id for this adapter, stamped into every row it emits.
+ */
+export const OSM_ADAPTER_ID = "osm"
+
+/**
+ * OpenStreetMap's license. Share-alike: `SHARE_ALIKE_PATTERN` matches it, and `--exclude-share-alike` drops the rows.
+ */
+export const OSM_LICENSE = "ODbL-1.0"
+
+/**
+ * The per-row shape `@mailwoman/osm`'s `emit-corpus-jsonl` writes.
+ */
+interface OSMCorpusRow {
+	street?: string
+	number?: string
+	postcode?: string
+	suburb?: string
+	city?: string
+	unit?: string
+	place?: string
+	subdistrict?: string
+	district?: string
+	province?: string
+}
+
+/**
+ * A street value that is a name rather than a mapper's whole address line.
+ */
+const MAX_STREET_WORDS = 8
+
+/**
+ * Whether `addr:housenumber` holds a designator a person writes after or before the street: digits with an optional
+ * letter, fraction or dash suffix (`12`, `188a`, `14/E`, `1/1146`, `167-c`), or a one- or two-letter block prefix
+ * (`B-77`, `L58`, `R 948`, Karachi's plot numbering). `House 34, Road 4, Sector 9`, `Plot #27`, `-` and a name are
+ * not.
+ */
+export function housenumberIsDesignator(value: string): boolean {
+	const trimmed = value.trim()
+
+	return /^\d+[A-Za-z]?(?:[/-]\d*[A-Za-z]?)?$/u.test(trimmed) || /^[A-Za-z]{1,2}[-\s]?\d+[A-Za-z]?$/u.test(trimmed)
+}
+
+/**
+ * Whether `addr:street` is a street name: no comma, at most {@link MAX_STREET_WORDS} words, and not a direction (`Near
+ * Cozy Water Park`, `Opposite Askari Towers`, `Behind …`).
+ */
+export function isStreetName(value: string): boolean {
+	const trimmed = value.trim()
+
+	return (
+		trimmed.length > 0 &&
+		!trimmed.includes(",") &&
+		trimmed.split(/\s+/u).length <= MAX_STREET_WORDS &&
+		!/^(?:near|opp(?:osite)?|behind|beside|next to|adjacent)\b/iu.test(trimmed)
+	)
+}
+
+/**
+ * Split an `addr:city` that carries a neighborhood ahead of the city (`Mirpur 10, Dhaka` → locality `Dhaka`, head
+ * `Mirpur 10`). A value without a comma is the locality alone.
+ */
+export function splitCityValue(value: string): { locality: string; head: string | null } {
+	const parts = value
+		.split(",")
+		.map((part) => part.trim())
+		.filter((part) => part.length > 0)
+
+	if (parts.length < 2) return { locality: value.trim(), head: null }
+
+	return { locality: parts.at(-1)!, head: parts.slice(0, -1).join(", ") }
+}
+
+/**
+ * Values mappers write for "none".
+ */
+const PLACEHOLDERS = new Set(["n/a", "na", "none", "-", "nil"])
+
+function clean(value: string | undefined): string | null {
+	const trimmed = value?.trim() ?? ""
+
+	return trimmed && !PLACEHOLDERS.has(trimmed.toLowerCase()) ? trimmed : null
+}
+
+function parseLine(line: string): OSMCorpusRow | null {
+	const trimmed = line.trim()
+
+	if (!trimmed || trimmed.startsWith("#")) return null
+
+	const parsed = tryParsingJSON(trimmed)
+
+	return parsed && typeof parsed === "object" ? (parsed as OSMCorpusRow) : null
+}
+
+/**
+ * Map one JSONL row onto the components the corpus asserts, or null when the row has no usable street.
+ */
+export function componentsForOSMRow(row: OSMCorpusRow): CanonicalRow["components"] | null {
+	const street = clean(row.street)
+
+	if (!street || !isStreetName(street)) return null
+
+	const components: CanonicalRow["components"] = { street }
+	const number = clean(row.number)
+
+	if (number && housenumberIsDesignator(number)) {
+		components.house_number = number
+	}
+
+	const unit = clean(row.unit)
+
+	if (unit) {
+		components.unit = unit
+	}
+
+	const postcode = clean(row.postcode)
+
+	if (postcode && /^\d{4,6}$/u.test(postcode)) {
+		components.postcode = postcode
+	}
+
+	const city = clean(row.city)
+	const split = city ? splitCityValue(city) : null
+
+	if (split) {
+		components.locality = split.locality
+	}
+
+	// The first candidate that is a name of its own: not a comma-joined pair, not the street or the locality again.
+	const dependent = [row.suburb, row.subdistrict, row.district, row.place, split?.head]
+		.map((value) => clean(value ?? undefined))
+		.find(
+			(value) =>
+				value !== null &&
+				!value.includes(",") &&
+				!sameName(value, street) &&
+				(split === null || !sameName(value, split.locality))
+		)
+
+	if (dependent) {
+		components.dependent_locality = dependent
+	}
+
+	const province = clean(row.province)
+
+	if (province && (split === null || !sameName(province, split.locality))) {
+		components.region = province
+	}
+
+	// A street alone is not an address row; the coarse adapters already teach bare names. A number and a street is one:
+	// 41,000 of Vietnam's 70,069 rows carry nothing above the street, and `568 Đường Điện Biên Phủ` is the line a
+	// person types.
+	if (Object.keys(components).length === 1) return null
+
+	return components
+}
+
+/**
+ * The admin-generic prefixes a mapper puts in front of a Vietnamese place name (`Thành phố Hà Nội`, `Tỉnh Bắc Ninh`,
+ * `TP. Hồ Chí Minh`), compared away so a province that repeats the city is read as the repeat it is.
+ */
+const NAME_PREFIXES = /^(?:thanh pho|tinh|tp\.?|quan|phuong|huyen|thi xa)\s+/u
+
+/**
+ * Whether two place names are the same name: case, whitespace, diacritics and a leading admin generic folded (`Bắc
+ * Ninh` = `Bac Ninh`; `Hà Nội` = `Thành phố Hà Nội`).
+ */
+export function sameName(a: string, b: string): boolean {
+	const fold = (value: string): string =>
+		stripCombiningMarks(value)
+			.replaceAll("đ", "d")
+			.replaceAll("Đ", "D")
+			.toLowerCase()
+			.replaceAll(/\s+/gu, " ")
+			.trim()
+			.replace(NAME_PREFIXES, "")
+
+	return fold(a) === fold(b)
+}
+
+export function createOSMAdapter(): CorpusAdapter {
+	return {
+		id: OSM_ADAPTER_ID,
+		defaultLicense: OSM_LICENSE,
+		description:
+			"OpenStreetMap addresses (ODbL, share-alike): per-country JSONL from a Geofabrik extract, for the countries no permissive source covers.",
+
+		async *rows(opts: AdapterOptions): AsyncIterable<CanonicalRow> {
+			if (!opts.country) {
+				throw new Error("osm adapter: --country is required (the JSONL is per-country and rows omit a country field)")
+			}
+
+			const country = opts.country
+			let emitted = 0
+
+			for await (const line of TextSpliterator.fromAsync(opts.inputPath)) {
+				if (opts.signal?.aborted) break
+
+				if (opts.limit !== undefined && emitted >= opts.limit) break
+
+				const row = parseLine(line)
+
+				if (!row) continue
+
+				const components = componentsForOSMRow(row)
+
+				if (!components) continue
+
+				const rendered = formatAddressRow(components, country, { singleLine: true })
+
+				if (!rendered) continue
+
+				const { raw, components: aligned } = rendered
+
+				yield {
+					raw,
+					components: aligned,
+					country,
+					source: OSM_ADAPTER_ID,
+					source_id: stableSourceID(OSM_ADAPTER_ID, aligned),
+					corpus_version: "",
+					license: OSM_LICENSE,
+				}
+
+				emitted++
+			}
+		},
+	}
+}
+
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const osmAdapter = createOSMAdapter()