@mailwoman/corpus 9.2.0 → 9.3.0

package/lib/tools/overture-subvenue.ts

@@ -0,0 +1,209 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Overture Places source for the sub-venue lexicon (#35 wave 2) — read the sub-venue-bearing
+ *   category slices of `poi.db` (spatial layer #1, `$MAILWOMAN_DATA_ROOT/poi/poi.db`) and yield
+ *   {@link SubVenueHarvestRow}s the lexicon builder consumes exactly like an OSM extract.
+ *
+ *   ── WHY OVERTURE AT ALL, when the OSM extractor already exists ────────────────────────────────────
+ *   Wave 1 measured `concourse` at 21 real Overture rows against 4 in the whole Great Britain OSM
+ *   extract, 3 of which are a street called CONCOURSE WAY. Overture's `airport_terminal` category is
+ *   curated venue-interior naming; OSM's `aeroway=terminal` is a building footprint that usually
+ *   carries the AIRPORT's name. The two sources fail differently, so both are read.
+ *
+ *   ── THE CATEGORY SET IS MEASURED, NOT GUESSED ────────────────────────────────────────────────────
+ *   A full scan of all 13,681,698 rows (2026-08-05, poi.db vintage 2026-05-20.0) counted, per
+ *   category, how many named rows carry a designator token. The ranking is NOT what a category name
+ *   predicts — `gas_station` leads the whole table with 12,996 hits, every one of them the token
+ *   `station` inside "Holiday Station" / "Chevron Station Seward", and `shoe_store` contributes 708
+ *   hits of `wing` because Red Wing sells boots. {@link OVERTURE_SUBVENUE_CATEGORIES} is the four
+ *   categories whose hits survived reading the distribution; the rejects are listed below it so nobody
+ *   re-proposes them.
+ *
+ *   ── poi.db IS FOUR COUNTRIES ─────────────────────────────────────────────────────────────────────
+ *   Measured the same day: US 11,521,612 / CA 794,418 / FR 721,352 / MX 644,316, and nothing else. The
+ *   shipped layer is not a world gazetteer, so Overture can attest en-US, en-CA, fr-FR and es-MX
+ *   surfaces and NOTHING ELSE. Every non-Latin designator the corpus task asks for — `ターミナル`,
+ *   `Halle`, `Flügel` — has to come from the OSM leg. Do not read a zero count here as evidence of
+ *   absence in the world; it is evidence of absence in four countries.
+ *
+ *   ── The row shape fits; the PROVENANCE STAMP did not ─────────────────────────────────────────────
+ *   Wave 1's `OSMSubVenueRow` was written to accept a non-OSM row, and it does: an Overture row is
+ *   `{ designatorID, name }` with no `ref` and no `localizedNames`. What did NOT fit is
+ *   `extractAttestedPhrases`, which hardcoded `osm:name` as the surface's `source`. Feeding Overture
+ *   rows through it unchanged would have labelled every Overture surface as OSM-attested — a
+ *   provenance lie, and under ODbL a consequential one. Hence the `source`/`region` options on that
+ *   function and the source-neutral {@link SubVenueHarvestRow} name.
+ */
+
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+
+import type { SubVenueHarvestRow } from "#tools/sub-venue-lexicon"
+
+/**
+ * Overture Places category → the designator its rows attest.
+ *
+ * Each entry carries the 2026-08-05 full-scan measurement in a comment: `rows` is the category's total, `hits` is how
+ * many of its named rows contain any designator token, and the token list is the top of that distribution.
+ *
+ * REJECTED, with the number that rejected them — do not re-add without a fresh census:
+ *
+ * - `gas_station` (12,996 hits) — all `station` inside a brand name (Holiday Station, Chevron Station Seward).
+ * - `fire_station` (10,377) — same, plus 330 `hall` from fire halls, which are venues rather than sub-venues.
+ * - `town_hall` (5,528) — `City Hall` is a whole building, the `venue` tier, not interior structure.
+ * - `building_supply_store` (4,030) — `building` inside "Allied Building Products".
+ * - `jehovahs_witness_place_of_worship` (2,334) — every hit is "Kingdom Hall of Jehovah's Witnesses".
+ * - `shoe_store` (909, of which 708 `wing`) — Red Wing. This one is a CONFOUND BOARD entry, not a source.
+ * - `college_university` (3,697) — 2,082 `campus`, but the row names the whole institution; `campus_building` is the
+ *   interior slice and is kept instead.
+ * - `airport` (6,000 rows, 4,302 hits) — 4,071 of them are the token `airport` in the aerodrome's own name. Venue tier,
+ *   already covered by OurAirports, and it drowns the interior signal.
+ * - `transport_interchange` (1 row), `rail_facility_or_service` (81 rows, 2 hits) — too small to matter.
+ * - `public_transit_facility_or_service` (2,274 rows, 185 hits) — 161 are `station` naming the station itself.
+ */
+export const OVERTURE_SUBVENUE_CATEGORIES: Readonly<Record<string, string>> = {
+	// 1,022 rows / 669 hits — terminal 266, concourse 19, gate 13, hall 4. The densest interior naming
+	// in the layer and the reason this reader exists.
+	airport_terminal: "terminal",
+	// 7,366 rows / 3,382 hits — hall 2,134, building 1,019, campus 209. US academic halls and numbered
+	// campus buildings: "UAA Cuddy Hall", "UAA Science Building". The row is a building ON a campus, so
+	// `campus` is its CONTEXT designator; the phrase found inside the name decides the record it
+	// attests, which for these rows is mostly `hall`.
+	campus_building: "campus",
+	// 443 rows / 301 hits — pier 282, terminal 17.
+	pier: "pier",
+	// 388 rows / 66 hits — airport 36, terminal 20, concourse 5, gate 3. Small, but the hits are almost
+	// all genuine ("Delta Sky Club Concourse B").
+	airport_lounge: "terminal",
+}
+
+/**
+ * The `poi` and `poi_category_codes` columns this reader touches, declared LOCALLY.
+ *
+ * `@mailwoman/resolver-wof-sqlite` owns the full `POIDatabase` interface, and `@mailwoman/corpus` does not depend on it
+ * — the same dependency-direction call `sub-venue-lexicon.ts` makes for `@mailwoman/osm`'s row type. This is a
+ * read-only projection of four columns; `overture-subvenue.test.ts` builds a fixture with exactly this DDL, so a column
+ * rename upstream fails a test here rather than throwing at runtime against a 3.9 GB database nobody has in CI.
+ */
+interface POIReadDatabase {
+	poi: {
+		category_id: number
+		name: string | null
+		country: string
+	}
+	poi_category_codes: {
+		id: number
+		category: string
+	}
+	layer_manifest: {
+		name: string
+		source_vintage: string
+	}
+}
+
+/**
+ * The layer's `source_vintage` — the Overture release the rows came from (`2026-05-20.0`), for the lexicon's
+ * `sources[]`.
+ *
+ * Read off the database rather than passed in, because a vintage a caller types is a vintage that goes stale silently.
+ * The layer-contract tables are part of every layer database by construction — see `docs/engineering/reference/
+ * layer-contract.mdx` — so there is no version of poi.db where this is absent.
+ */
+export async function readOvertureLayerVintage(databasePath: string): Promise<string> {
+	using kdb = new DatabaseClient<POIReadDatabase>(databasePath, { readOnly: true })
+
+	const row = await kdb
+		.selectFrom("layer_manifest")
+		.select("source_vintage")
+		.where("name", "=", "poi")
+		.executeTakeFirst()
+
+	return row?.source_vintage ?? ""
+}
+
+export interface ReadOvertureSubVenuesOptions {
+	/**
+	 * Path to `poi.db`. Typically `dataRootPath("poi", "poi.db")`.
+	 */
+	databasePath: string
+	/**
+	 * Category → designator map. Defaults to {@link OVERTURE_SUBVENUE_CATEGORIES}.
+	 */
+	categories?: Readonly<Record<string, string>>
+	/**
+	 * Restrict to these ISO 3166-1 alpha-2 countries. Omit for all four the layer carries.
+	 */
+	countries?: readonly string[]
+}
+
+/**
+ * One Overture row plus the country it came from — {@link SubVenueHarvestRow} widened by the field the layer has and an
+ * OSM extract does not (a Geofabrik extract's country is a property of the invocation, so OSM rows carry `country:
+ * ""`).
+ */
+export interface OvertureSubVenueRow extends SubVenueHarvestRow {
+	/**
+	 * ISO 3166-1 alpha-2, straight off the Overture partition.
+	 */
+	country: string
+	/**
+	 * The Overture category the row was read from, so a surface's provenance survives past the designator.
+	 */
+	category: string
+}
+
+/**
+ * Read the sub-venue-bearing category slices of `poi.db`.
+ *
+ * Cold path, already async, no interface constraint — so Kysely, per the repo's inline-SQL rule.
+ *
+ * `category_id` is the SECOND component of poi.db's clustered `(h3_cell, category_id, …)` primary key, which reads like
+ * a full 13.7M-row scan and is not one: SQLite skip-scans the leading `h3_cell` and the whole four-category read
+ * returned 9,219 rows in **1.4 s** on the shipped layer (2026-08-05). A JS-side scan of every row to survey the same
+ * question took 52 s, which is the number to remember if you are tempted to filter in JS instead.
+ */
+export async function readOvertureSubVenues(options: ReadOvertureSubVenuesOptions): Promise<OvertureSubVenueRow[]> {
+	const categories = options.categories ?? OVERTURE_SUBVENUE_CATEGORIES
+
+	using kdb = new DatabaseClient<POIReadDatabase>(options.databasePath, { readOnly: true })
+
+	const codes = await kdb
+		.selectFrom("poi_category_codes")
+		.select(["id", "category"])
+		.where("category", "in", Object.keys(categories))
+		.execute()
+
+	if (!codes.length) return []
+
+	const designatorByID = new Map<number, string>()
+	const categoryByID = new Map<number, string>()
+
+	for (const code of codes) {
+		const designator = categories[code.category]
+
+		if (!designator) continue
+		designatorByID.set(code.id, designator)
+		categoryByID.set(code.id, code.category)
+	}
+
+	let query = kdb
+		.selectFrom("poi")
+		.select(["category_id", "name", "country"])
+		.where("category_id", "in", [...designatorByID.keys()])
+		.where("name", "is not", null)
+
+	if (options.countries?.length) {
+		query = query.where("country", "in", [...options.countries])
+	}
+
+	const rows = await query.execute()
+
+	return rows.map((row) => ({
+		designatorID: designatorByID.get(row.category_id)!,
+		name: row.name,
+		country: row.country,
+		category: categoryByID.get(row.category_id)!,
+	}))
+}

package/lib/tools/postcode-triples.ts

@@ -0,0 +1,363 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Extract `(postcode, locality, region, country)` tuples for the `trailing-region` slice.
+ *
+ *   This step used to be a one-off. Its output survived — 17,908 rows at
+ *   `$MAILWOMAN_DATA_ROOT/corpus/tuples/trailing-region-structured-tuples.jsonl` — but the code that produced it did
+ *   not, so a note describing the join was the only record and it did not match what the databases contain. That is the
+ *   reason this file exists: the slice is unbuildable for a new country without it.
+ *
+ *   ## Two sources, because one route does not reach every country
+ *
+ *   - **`postalcode-intl.db`** carries a real `parent_id` that resolves in the admin gazetteer. Measured share of rows
+ *     with a parent: NL 97.5%, FR 90.7%, DE 66.1%, ES 34.9%, IT 27.4%; of those, 93.8–100% land on a `locality` or
+ *     `localadmin`, and the region comes from that place's own ancestry. It is the ONLY slice with this — every
+ *     `postalcode-geonames-*` and `postalcode-<cc>-overture.db` row reads `parent_id = 0`.
+ *   - **GeoNames postal exports** carry the place and admin1 NAMES in columns 3 and 4, so there is nothing to join.
+ *     `mailwoman corpus fetch geonames-postal` puts them on disk.
+ *
+ *   A nearest-locality-centroid join was measured as the general fallback and REJECTED: scored against the `parent_id`
+ *   truth, it agreed NL 81.1% / DE 44.7% / ES 35.1% / FR 29.0% / IT 13.5%. A locality's centroid sits at its middle, so
+ *   an edge postcode is routinely nearer a neighbouring town's centroid. Do not reach for it again.
+ *
+ *   ## The hub cap is PER COUNTRY, because a pooled one is a mixture
+ *
+ *   A few localities act as catch-all parents — `Schwedt/Oder` claims 9,222 DE postcodes against a DE median of 1. Left
+ *   in, a handful of places dominate the slice. But the distribution differs so much by country that one threshold is
+ *   not one rule: a p99 pooled across the five countries lands at 522, which keeps 100% of ES and IT, 83% of FR, 49% of
+ *   NL and 19% of DE.
+ *
+ *   So the bound is a QUOTA and not a threshold. A threshold DELETES a locality that exceeds it, which removes exactly
+ *   the largest cities — the places a parser most needs to have seen. A quota keeps every locality and bounds how many
+ *   of its postcodes ride along, which is the balance the cap was reaching for without the deletion.
+ *
+ *   ## Placement is data, not a formatting choice
+ *
+ *   Each tuple is stamped with its country's {@link PostcodePlacement}. The same digits change tag with position, so a
+ *   tuple that does not carry its placement teaches whichever convention the recipe happens to default to — see the
+ *   recipe's header for the measurement.
+ */
+
+import { dataRootPath } from "@mailwoman/core/data-root"
+import { pathExists } from "@mailwoman/core/fs/readers"
+import type { WOFDatabase } from "@mailwoman/resolver-wof-sqlite/schema"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+import { join } from "path-ts"
+import { TSVSpliterator } from "spliterator"
+
+import { GEONAMES_POSTAL_COLUMNS } from "#adapters/geonames-postal/adapter"
+import type { PostcodePlacement } from "#recipes/scaffold"
+import { escapeSQLString } from "#utils/parquet"
+
+/**
+ * One extracted tuple, in the shape `readTuples` yields and the recipe consumes.
+ */
+export interface PostcodeTriple {
+	postcode: string
+	/**
+	 * The segment before the locality, when the source has one. A slice whose every row begins with the locality teaches
+	 * that the first named segment IS the locality, and that flips the model's default. Measured on the v4.8.0 candidate,
+	 * which had no such segment — `Ye Three Lords, 27 Minories, London EC3N 1DE` came back `locality: "Ye Three Lords"`
+	 * with the venue and the street both gone, and 11 of its 25 regressions were venue-led rows across seven countries.
+	 */
+	dependentLocality?: string
+	locality: string
+	region: string
+	country: string
+	cc: string
+	locale: string
+	postcodePlacement: PostcodePlacement
+}
+
+/**
+ * Where a country writes the postcode, and the locale tag its rows carry.
+ *
+ * A country is in this table only when a gauntlet board row ATTESTS its surface. An absent country is not an oversight
+ * to be filled in by guessing: extracting it with the wrong placement teaches a convention that country does not use,
+ * which is worse than not teaching it at all. `LEADING_POSTCODE_COUNTRIES` in `@mailwoman/neural`'s
+ * `placetype-pair-prior.ts` draws the same line for the same reason.
+ *
+ * AU and ZA are the worked examples of the bar. Both look like obvious additions and neither qualifies: the board's AU
+ * rows are bare-city (`Melbourne`, `Sydney, Australia`) and carry no postcode at all, so nothing here says where AU
+ * writes it; and ZA's `14 Long St, Green Point, Cape Town, 8001` carries no REGION, which this slice requires — a fact
+ * its GeoNames export agrees with, at 100% place and 0% admin1.
+ */
+export const POSTCODE_CONVENTIONS: ReadonlyMap<string, { placement: PostcodePlacement; locale: string }> = new Map([
+	// `Rue de l'Église, 3, 29217 Plougonvelin, Bretagne, France` and its siblings — `fr_structured`, `de_structured`,
+	// `es_structured`, `it_structured`, `pt_structured`, `mx_supermanzana`, `nl-op4-p-r-sloterdijk`.
+	["FR", { placement: "leading", locale: "fr-FR" }],
+	["DE", { placement: "leading", locale: "de-DE" }],
+	["ES", { placement: "leading", locale: "es-ES" }],
+	["IT", { placement: "leading", locale: "it-IT" }],
+	["NL", { placement: "leading", locale: "nl-NL" }],
+	["PT", { placement: "leading", locale: "pt-PT" }],
+	["MX", { placement: "leading", locale: "es-MX" }],
+	// `…, Barcelona 6001, Anzoátegui, Venezuela` — the four `ve_city_postcode_trailing_state` rows. No postcode source
+	// on disk and GeoNames does not publish VE, so this entry currently yields nothing; it is here because the
+	// placement is what makes the absence legible.
+	["VE", { placement: "after_locality", locale: "es-VE" }],
+	// `12 MG Road, Indiranagar, Bengaluru, Karnataka 560038, India` — three `in_*` rows, and `AGENTS.md` says the same
+	// ("en-IN is absent BECAUSE the PIN goes last"). The one trailing placement with real data behind it.
+	["IN", { placement: "after_region", locale: "en-IN" }],
+])
+
+/**
+ * How many postcodes one locality may contribute.
+ *
+ * A quota rather than a cutoff — see the header. It bounds repetition without deleting a locality: a city with 9,222
+ * postcodes contributes this many and stays in the slice.
+ */
+export const DEFAULT_LOCALITY_QUOTA = 24
+
+/**
+ * Take at most `quota` tuples per locality, in the order they arrive.
+ *
+ * Order matters and is the caller's to choose: both readers below walk their source in id / file order, which is stable
+ * across runs, so the same quota selects the same rows.
+ */
+export function applyLocalityQuota(
+	triples: readonly PostcodeTriple[],
+	quota: number = DEFAULT_LOCALITY_QUOTA
+): PostcodeTriple[] {
+	const seen = new Map<string, number>()
+	const kept: PostcodeTriple[] = []
+
+	for (const triple of triples) {
+		const key = `${triple.cc} ${triple.locality}`
+		const n = seen.get(key) ?? 0
+
+		if (n >= quota) continue
+
+		seen.set(key, n + 1)
+		kept.push(triple)
+	}
+
+	return kept
+}
+
+/**
+ * Take at most `budget` tuples per COUNTRY, in the order they arrive.
+ *
+ * A per-locality quota bounds how often one place repeats; it cannot bound a country. IN has 128,152 distinct
+ * localities, so even at a quota of ONE it contributes 63,533 rows against 39,790 from the other seven combined — the
+ * slice would teach the trailing surface as an Indian fact rather than a general one, and at 103,323 rows it would take
+ * 30% of an 8,000-step run's sample budget at three reps per row.
+ *
+ * Applied AFTER {@link applyLocalityQuota}, so a country's budget is spent on breadth (many localities) rather than on
+ * one city's postcode list.
+ */
+export function applyCountryBudget(
+	triples: readonly PostcodeTriple[],
+	budget: number | ReadonlyMap<string, number>
+): PostcodeTriple[] {
+	const spent = new Map<string, number>()
+	const kept: PostcodeTriple[] = []
+
+	for (const triple of triples) {
+		const cap = typeof budget === "number" ? budget : budget.get(triple.cc)
+
+		if (cap === undefined) continue
+
+		const n = spent.get(triple.cc) ?? 0
+
+		if (n >= cap) continue
+
+		spent.set(triple.cc, n + 1)
+		kept.push(triple)
+	}
+
+	return kept
+}
+
+/**
+ * Read triples out of `postalcode-intl.db` by following each postcode's `parent_id` into the admin gazetteer and that
+ * place's ancestry to a region.
+ *
+ * A postcode whose parent does not resolve, or whose parent has no region ancestor, is DROPPED rather than emitted with
+ * a blank — the recipe already skips a tuple with no region, and a blank here would hide how much of the source is
+ * actually reachable.
+ */
+export async function readTriplesFromParentJoin(
+	countries: readonly string[],
+	options: { postcodeDB?: string; adminDB?: string } = {}
+): Promise<PostcodeTriple[]> {
+	const postcodeDB = options.postcodeDB ?? String(dataRootPath("wof", "postalcode-intl.db"))
+	const adminDB = options.adminDB ?? String(dataRootPath("wof", "admin-global-priority-importance.db"))
+
+	if (!(await pathExists(postcodeDB)) || !(await pathExists(adminDB))) return []
+
+	using db = new DatabaseClient<WOFDatabase>(adminDB, { readOnly: true })
+
+	db.exec(`ATTACH DATABASE '${escapeSQLString(postcodeDB)}' AS pc`)
+
+	const statement = db.prepare(`
+		SELECT p.name AS postcode, a.name AS locality, r.name AS region, c.name AS country, p.country AS cc
+		FROM pc.spr p
+		JOIN spr a ON a.id = p.parent_id AND a.placetype IN ('locality', 'localadmin')
+		JOIN ancestors anc ON anc.id = a.id AND anc.ancestor_placetype = 'region'
+		JOIN spr r ON r.id = anc.ancestor_id
+		JOIN ancestors cnc ON cnc.id = a.id AND cnc.ancestor_placetype = 'country'
+		JOIN spr c ON c.id = cnc.ancestor_id
+		WHERE p.country = ? AND p.parent_id > 0
+		ORDER BY p.id
+	`)
+
+	const out: PostcodeTriple[] = []
+
+	for (const cc of countries) {
+		const convention = POSTCODE_CONVENTIONS.get(cc)
+
+		if (!convention) continue
+
+		for (const row of statement.all(cc) as Array<Record<string, string>>) {
+			if (!row["postcode"] || !row["locality"] || !row["region"]) continue
+
+			out.push({
+				postcode: row["postcode"],
+				locality: row["locality"],
+				region: row["region"],
+				country: row["country"] ?? "",
+				cc,
+				locale: convention.locale,
+				postcodePlacement: convention.placement,
+			})
+		}
+	}
+
+	return out
+}
+
+/**
+ * A predicate answering whether a name is a LOCALITY the admin gazetteer knows, for one country.
+ *
+ * The parent-join reader gets this for free — its query restricts the parent to `locality`/`localadmin`, so every name
+ * it emits is one by construction. The GeoNames reader has no such guarantee, and the gap is large enough to matter:
+ * sampling 400 rows per country against the gazetteer, the share of GeoNames place names that name a locality we know
+ * is PT 75%, IN 62%, **MX 41%**. The Mexican misses are colonias — `Zona Centro`, `San Fernando INFONAVIT`, `FOVISSSTE
+ * 3a Sección` — and a row teaching one of those as `locality` trains the locality/dependent_locality boundary in the
+ * wrong direction. Dropping the row instead costs coverage and teaches nothing false, which is the better of the two.
+ *
+ * Returns a predicate that answers `true` for everything when the gazetteer is not on disk, so a checkout without it
+ * builds the same rows it did before rather than silently emitting none.
+ */
+export async function createKnownLocalityCheck(country: string, adminDB?: string): Promise<(name: string) => boolean> {
+	const path = adminDB ?? String(dataRootPath("wof", "admin-global-priority-importance.db"))
+
+	if (!(await pathExists(path))) return () => true
+
+	using db = new DatabaseClient<WOFDatabase>(path, { readOnly: true })
+
+	const names = new Set<string>()
+
+	for (const row of db
+		.prepare("SELECT name FROM spr WHERE country = ? AND placetype IN ('locality', 'localadmin')")
+		.all(country) as Array<{ name: string | null }>) {
+		if (row.name) {
+			names.add(row.name.toLowerCase())
+		}
+	}
+
+	// An empty set means the gazetteer has no localities for this country at all, which is a coverage fact about the
+	// gazetteer rather than a verdict on the source — so check nothing rather than drop everything.
+	if (!names.size) return () => true
+
+	return (name: string) => names.has(name.toLowerCase())
+}
+
+/**
+ * Read triples straight out of a GeoNames `<CC>.txt` export — no join, the names are columns 3 and 4.
+ *
+ * COLUMN 3 IS NOT THE LOCALITY. It is the finest-grained named place for the code, and for `560001` that is `Mahatma
+ * Gandhi Road` — a STREET — while the city, `Bengaluru`, is column 5 (admin2). MX is the same shape (`Roma Norte` is a
+ * colonia inside `Cuauhtémoc`) and so is PT (`Abrigada` inside `Alenquer`). Reading column 3 as the locality is how the
+ * v4.8.0 slice came to teach street names as cities. So `admin2` is the locality, `admin1` the region, and column 3 the
+ * DEPENDENT locality — which is also the left context the slice needs.
+ *
+ * WHICH COUNTRIES THIS READER CAN SERVE. It needs `admin2` (the city) and `admin1` (the region), and a country can
+ * publish one without the other. Measured 2026-08-23 across the exports on disk:
+ *
+ * | country    | rows      | admin1 | admin2 | usable here                     |
+ * | ---------- | --------: | -----: | -----: | ------------------------------- |
+ * | PT, MX, IN | 145k–207k | 100%   | 100%   | yes                             |
+ * | BD, LK     | 1.3k–1.8k | 100%   | 100%   | yes                             |
+ * | PH         | 2,317     | 88%    | 88%    | yes, 88% of rows                |
+ * | PK         | 2,563     | 100%   | **0%** | NO — no city column             |
+ * | TH         | 903       | 100%   | **1%** | NO — effectively no city column |
+ * | ID         | 81,058    | **0%** | 0%     | NO — no region either           |
+ * | ZA         | 3,920     | **0%** | —      | NO                              |
+ *
+ * A country in the NO rows yields zero from this reader, and that is the correct outcome rather than a gap to route
+ * around: taking column 3 as the locality is what made the v4.8.0 slice train `Mahatma Gandhi Road` as a city. If one
+ * of them is wanted, it needs a city column from somewhere else, not a relaxed mapping.
+ *
+ * NOT PUBLISHED AT ALL by GeoNames, checked the same day: VE, VN, NP, MM, KH. Those are acquisition questions, and for
+ * VE specifically OpenAddresses 404s too — see the arc retrospective.
+ *
+ * Three source properties a caller cannot see from a row count, all handled here. Hyphen-format countries publish each
+ * code TWICE (`3750-000` and `3750000`, exactly 2.00× for PT and PL), so the first surface of a code wins and its twin
+ * is dropped. Some countries populate the place but not admin1 — ZA is 100% place, 0% region — which yields nothing
+ * this slice can use, so those rows are dropped rather than emitted with a blank region. And the "place name" is often
+ * a SUB-locality, which {@link createKnownLocalityCheck} filters.
+ */
+export async function readTriplesFromGeonames(
+	country: string,
+	path: string,
+	countryName: string,
+	options: { isKnownLocality?: (name: string) => boolean } = {}
+): Promise<PostcodeTriple[]> {
+	const convention = POSTCODE_CONVENTIONS.get(country)
+
+	if (!convention || !(await pathExists(path))) return []
+
+	const isKnownLocality = options.isKnownLocality ?? (await createKnownLocalityCheck(country))
+	const out: PostcodeTriple[] = []
+	const seen = new Set<string>()
+
+	for await (const cells of TSVSpliterator.fromAsync(path, { header: false }) as AsyncIterable<string[]>) {
+		const postcode = (cells[GEONAMES_POSTAL_COLUMNS.postcode] ?? "").trim()
+		const dependentLocality = (cells[GEONAMES_POSTAL_COLUMNS.place] ?? "").trim()
+		const locality = (cells[GEONAMES_POSTAL_COLUMNS.admin2Name] ?? "").trim()
+		const region = (cells[GEONAMES_POSTAL_COLUMNS.admin1Name] ?? "").trim()
+
+		if (!postcode || !locality || !region) continue
+
+		// The check applies to the LOCALITY — admin2 — not to the fine-grained name, which is expected to be a street or
+		// a colonia and is emitted as the dependent locality rather than dropped.
+		if (!isKnownLocality(locality)) continue
+
+		// A dependent locality that merely repeats its parent teaches a doubled segment, not a boundary.
+		const dep = dependentLocality && dependentLocality !== locality ? dependentLocality : ""
+
+		// The bare twin of a punctuated code carries no new fact, and keeping both doubles the country's weight.
+		const key = `${postcode.replaceAll("-", "")} ${locality} ${dep}`
+
+		if (seen.has(key)) continue
+
+		seen.add(key)
+
+		out.push({
+			postcode,
+			...(dep ? { dependentLocality: dep } : {}),
+			locality,
+			region,
+			country: countryName,
+			cc: country,
+			locale: convention.locale,
+			postcodePlacement: convention.placement,
+		})
+	}
+
+	return out
+}
+
+/**
+ * Resolve a GeoNames export path under the standard fetch out-root.
+ */
+export function geonamesPostalPath(country: string, sourcesRoot?: string): string {
+	const root = sourcesRoot ?? String(dataRootPath("corpus", "sources"))
+
+	return join(root, "geonames-postal", `${country.toUpperCase()}.txt`)
+}