@mailwoman/resolver-wof-sqlite 8.0.0 → 8.2.0

package/fst-types.ts

@@ -16,6 +16,13 @@ export interface PlaceEntry {
 	importance: number
 	lat: number
 	lon: number
+	/**
+	 * Surface-ambiguity class (survey #4): how many DISTINCT countries carry a place with THIS entry's accepting surface,
+	 * counted over the whole admin DB at build time (clamped to 255). A property of the surface, not the place — the same
+	 * place reached via different alias surfaces reports each surface's own count. `undefined` = built without ambiguity
+	 * data (pre-2026-07-27 artifacts) — NEVER conflate with 1 (the unambiguous case); the meaning-of-zero rule.
+	 */
+	crossCountryBranches?: number
 }
 
 export type PlacetypeID =
@@ -60,6 +67,14 @@ export interface FSTProvenance {
 	importanceMatches: number
 	sourceDB?: string
 	modelCardVersion?: string
+	/**
+	 * Degenerate-surface curation policy applied at build time (absent = uncurated build).
+	 */
+	exclusionPolicy?: string
+	/**
+	 * Name insertions refused by the curation policy.
+	 */
+	excludedInsertions?: number
 }
 
 export interface BuildFSTOpts {
@@ -67,6 +82,34 @@ export interface BuildFSTOpts {
 	countries?: string[]
 	placetypes?: PlacetypeID[]
 	languages?: string[]
+	/**
+	 * Degenerate-surface curation (build-time; the ASR-contextual-biasing "prune the bias list" discipline). A name whose
+	 * FULL normalized token sequence joins to a member of this set is never inserted — the surface carries no
+	 * discriminative value as a bias key (bare function words: "la"; bare street-type words: "boulevard"). The FST is a
+	 * bias list, not the gazetteer of record — the resolver's candidate tables are untouched, so excluded places stay
+	 * findable; they just stop nudging the decoder on degenerate keys. Keys must be `normalizeTokens(...).join(" ")`.
+	 */
+	excludeSurfaces?: ReadonlySet<string>
+	/**
+	 * Compositional clause of the same policy: refuse a name whose EVERY normalized token is a member (e.g. "de la") — a
+	 * surface made entirely of function words cannot be discriminative. Source this from stopwords only, never
+	 * street-type words ("Avenue Road" is a real name; "de la" is not).
+	 */
+	excludeAllTokensOf?: ReadonlySet<string>
+	/**
+	 * Recorded verbatim into provenance when either exclusion set is supplied.
+	 */
+	exclusionPolicy?: string
+	/**
+	 * Surface-ambiguity classes (survey #4, 2026-07-27): normalized-join surface → the number of DISTINCT countries
+	 * (across the WHOLE admin DB, not just this build's country scope) with a place carrying that surface. When supplied,
+	 * every inserted place row records the count for ITS accepting surface (`PlaceEntry.crossCountryBranches`) — an entry
+	 * accessible under several surfaces records each surface's own count. Serialized into the place row's former `_pad`
+	 * byte with presence signaled by header flags bit0, so VERSION stays put and pre-ambiguity artifacts read as "no
+	 * data" (never "0 branches" — the meaning-of-zero rule). No decoder consumes it yet; consumers (FST-prior tempering,
+	 * the Option-A evidence channel) arrive behind their own measured gates.
+	 */
+	surfaceCountryCounts?: ReadonlyMap<string, number>
 	onProgress?: (phase: string, detail?: string) => void
 }
 

package/fts-query.ts

@@ -0,0 +1,84 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Query shaping for the FTS5 lookup: placetype normalization and the MATCH-expression sanitizer.
+ *   Both turn a caller's loose input into something SQLite's FTS5 parser accepts without throwing —
+ *   an unescaped quote or a bare `*` is a syntax error, not an empty result.
+ */
+
+import type { FindPlaceQuery, WOFPlacetype } from "./types.ts"
+
+export function normalizePlacetypes(p: FindPlaceQuery["placetype"]): WOFPlacetype[] | null {
+	if (!p) return null
+
+	return Array.isArray(p) ? p : [p]
+}
+
+/**
+ * Make an arbitrary user-typed string safe for FTS5 MATCH.
+ *
+ * FTS5 has its own query syntax (`"phrase"`, `term1 OR term2`, `prefix*`, NEAR/N, etc.). Letting raw user input through
+ * means a user typing `Paris's` or `St. (Petersburg)` causes a syntax error.
+ *
+ * Per-token rules:
+ *
+ * - Strip all punctuation except trailing `*` from each whitespace-separated token.
+ * - **Trailing `*`** is preserved as FTS5 **prefix syntax** — `627*` becomes the literal `627*` (unquoted). The caller
+ *   signaled they want a prefix; respect that.
+ * - All other tokens are wrapped in `"..."` as a single-word phrase. Conservative — handles apostrophes, parens, accented
+ *   input, etc. safely.
+ * - Multiple tokens join with implicit AND.
+ *
+ * Examples:
+ *
+ * - `"Paris"` → `"Paris"` (phrase)
+ * - `"627*"` → `627*` (prefix)
+ * - `"St. (Petersburg)"` → `"St" "Petersburg"` (two phrases, AND-joined)
+ * - `"Thiron-Gardais"` → `"Thiron" "Gardais"` (intra-token punctuation SPLITS — #945; fusing to `ThironGardais` matched
+ *   nothing because the FTS doc tokenizes the hyphenated name as two terms)
+ * - `"110 00"` with `fuseTokens` (postcode-typed) → `"110" "00"` per-token fused — the #920 name law
+ * - `"Pari* TX"` → `Pari* "TX"` (mixed prefix + phrase)
+ * - `"*"` alone → `""` (no body → drop)
+ */
+export function sanitizeFTSQuery(text: string, opts?: { fuseTokens?: boolean }): string {
+	const out: string[] = []
+
+	for (const rawToken of text.normalize("NFKC").split(/\s+/u)) {
+		const trimmed = rawToken.trim()
+
+		if (!trimmed) continue
+		const hasPrefixStar = trimmed.endsWith("*")
+
+		// #920 name law (postcode-typed queries ONLY): delete intra-token punctuation and FUSE the
+		// remainder — postal names are stored in this collapsed shape ("SW1A" stays one term).
+		if (opts?.fuseTokens) {
+			const body = trimmed.replaceAll(/[^\p{L}\p{N}]/gu, "")
+
+			if (!body) continue
+			out.push(hasPrefixStar ? `${body}*` : `"${body.replaceAll('"', '""')}"`)
+
+			continue
+		}
+
+		// Everything else SPLITS on intra-token punctuation — the behavior the docstring always
+		// promised ("St. (Petersburg)" → two phrases). The old code DELETED punctuation instead,
+		// fusing "Thiron-Gardais" into the unmatchable single term `ThironGardais` while the FTS
+		// doc holds two terms (#945 — the entire hyphenated-name class missed at the raw lookup;
+		// masked for years because pre-splice tokenizers never emitted hyphen-preserved values).
+		const parts = trimmed.split(/[^\p{L}\p{N}]+/u).filter(Boolean)
+
+		if (!parts.length) continue
+
+		for (let i = 0; i < parts.length; i++) {
+			const body = parts[i]!.replaceAll("*", "")
+
+			if (!body) continue
+			// The caller's trailing `*` applies to the FINAL part ("Thiron-Gard*" → "Thiron" Gard*).
+			out.push(hasPrefixStar && i === parts.length - 1 ? `${body}*` : `"${body.replaceAll('"', '""')}"`)
+		}
+	}
+
+	return out.join(" ")
+}

package/fts.ts

@@ -66,7 +66,9 @@ export const PLACE_SEARCH_TABLE = "place_search"
  */
 export const ALIAS_SEPARATOR = "\uE000"
 
-/** `char()` argument for {@link ALIAS_SEPARATOR} in SQL — keeps the SQL text plain ASCII. */
+/**
+ * `char()` argument for {@link ALIAS_SEPARATOR} in SQL — keeps the SQL text plain ASCII.
+ */
 const ALIAS_SEPARATOR_CODEPOINT = ALIAS_SEPARATOR.codePointAt(0) as number
 
 /**
@@ -93,7 +95,7 @@ const ALIAS_SEPARATOR_CODEPOINT = ALIAS_SEPARATOR.codePointAt(0) as number
  */
 export function aliasBagExactMatch(altNames: string | null, normalizedQuery: string, anyStrictExact: boolean): boolean {
 	if (altNames === null || altNames === "" || !normalizedQuery) return false
-	const norm = (s: string): string => s.toLowerCase().trim().replace(/\s+/g, " ")
+	const norm = (s: string): string => s.toLowerCase().trim().replaceAll(/\s+/g, " ")
 
 	if (altNames.includes(ALIAS_SEPARATOR)) {
 		return altNames.split(ALIAS_SEPARATOR).some((alias) => norm(alias) === normalizedQuery)
@@ -126,15 +128,25 @@ export const PLACE_POPULATION_TABLE = "place_population"
  * user.
  */
 export interface BuildPlaceSearchFTSResult {
-	/** Whether the FTS5 index was created (true) or already existed and was left alone (false). */
+	/**
+	 * Whether the FTS5 index was created (true) or already existed and was left alone (false).
+	 */
 	created: boolean
-	/** Number of rows in the `place_search` table after the call. */
+	/**
+	 * Number of rows in the `place_search` table after the call.
+	 */
 	indexedRows: number
-	/** Whether the R*Tree bbox index was created (true) or already existed (false). */
+	/**
+	 * Whether the R*Tree bbox index was created (true) or already existed (false).
+	 */
 	bboxCreated: boolean
-	/** Number of rows in the `place_bbox` R*Tree after the call. */
+	/**
+	 * Number of rows in the `place_bbox` R*Tree after the call.
+	 */
 	bboxIndexedRows: number
-	/** Wall-clock duration of the build step, in milliseconds. */
+	/**
+	 * Wall-clock duration of the build step, in milliseconds.
+	 */
 	durationMs: number
 }
 
@@ -183,6 +195,7 @@ export function buildPlaceSearchFTS(db: DatabaseSync, opts: BuildPlaceSearchFTSO
 
 	if (!ftsExisting || opts.drop) {
 		onProgress("creating")
+
 		db.exec(`
 			CREATE VIRTUAL TABLE ${PLACE_SEARCH_TABLE} USING fts5(
 				wof_id UNINDEXED,
@@ -191,7 +204,9 @@ export function buildPlaceSearchFTS(db: DatabaseSync, opts: BuildPlaceSearchFTSO
 				tokenize = 'unicode61 remove_diacritics 2'
 			);
 		`)
+
 		onProgress("populating")
+
 		// Excludes only definitively-not-current places. WOF's `is_current` carries TWO conventions:
 		// `-1` (modern Who's On First) and `1` (legacy Mapzen-era), both meaning "currently valid".
 		// Only `0` means "no longer current". Filtering on `= -1` strict (as Phase 4.2 did) excluded
@@ -220,8 +235,10 @@ export function buildPlaceSearchFTS(db: DatabaseSync, opts: BuildPlaceSearchFTSO
 				AND spr.is_deprecated = 0
 				AND spr.name IS NOT NULL;
 		`)
+
 		ftsCreated = true
 	}
+
 	const ftsCountRow = db.prepare(`SELECT COUNT(*) AS n FROM ${PLACE_SEARCH_TABLE}`).get() as { n: number }
 
 	// ─── R*Tree phase ────────────────────────────────────────────────
@@ -234,6 +251,7 @@ export function buildPlaceSearchFTS(db: DatabaseSync, opts: BuildPlaceSearchFTSO
 
 	if (!bboxExisting || opts.drop) {
 		onProgress("creating-bbox")
+
 		// R*Tree requires INTEGER PRIMARY KEY (id) + paired min/max for each indexed dimension.
 		// `rtree` (not `rtree_i32`) keeps coordinates as REAL — what we want for WGS-84.
 		db.exec(`
@@ -243,7 +261,9 @@ export function buildPlaceSearchFTS(db: DatabaseSync, opts: BuildPlaceSearchFTSO
 				min_lon, max_lon
 			);
 		`)
+
 		onProgress("populating-bbox")
+
 		// Only index places that have non-zero coordinates AND a real bbox. WOF stores both the
 		// centroid (latitude/longitude) and the bounding box (min_*/max_*). A subset of rows have
 		// all-zero coordinates — likely placeholders for deprecated / unmapped entries; the
@@ -266,8 +286,10 @@ export function buildPlaceSearchFTS(db: DatabaseSync, opts: BuildPlaceSearchFTSO
 				AND NOT (spr.min_latitude = 0 AND spr.max_latitude = 0
 				     AND spr.min_longitude = 0 AND spr.max_longitude = 0);
 		`)
+
 		bboxCreated = true
 	}
+
 	const bboxCountRow = db.prepare(`SELECT COUNT(*) AS n FROM ${PLACE_BBOX_TABLE}`).get() as { n: number }
 
 	// NOTE: `place_population` is NOT built here. `scripts/build-unified-wof.ts` extracts
@@ -299,12 +321,16 @@ export function placeSearchFTSExists(db: DatabaseSync): boolean {
 	return tableExists(db, PLACE_SEARCH_TABLE)
 }
 
-/** Returns true iff the `place_bbox` R*Tree table exists. Used for opt-in proximity lookup checks. */
+/**
+ * Returns true iff the `place_bbox` R*Tree table exists. Used for opt-in proximity lookup checks.
+ */
 export function placeBboxExists(db: DatabaseSync): boolean {
 	return tableExists(db, PLACE_BBOX_TABLE)
 }
 
-/** Returns true iff the `place_population` table exists. Used for opt-in population-ranking checks. */
+/**
+ * Returns true iff the `place_population` table exists. Used for opt-in population-ranking checks.
+ */
 export function placePopulationExists(db: DatabaseSync): boolean {
 	return tableExists(db, PLACE_POPULATION_TABLE)
 }

package/geo.ts

@@ -22,7 +22,9 @@
 // readers keep importing it from "./geo.ts" (the spatial dep is transitive via @mailwoman/resolver).
 export { haversineKm } from "@mailwoman/spatial"
 
-/** WGS-84 degrees → radians. */
+/**
+ * WGS-84 degrees → radians.
+ */
 function toRad(deg: number): number {
 	return (deg * Math.PI) / 180
 }
@@ -61,10 +63,14 @@ export function bboxAround(lat: number, lon: number, radiusKm: number): Bbox {
  */
 export type GeojsonPosition = [number, number, ...number[]]
 
-/** The two areal GeoJSON geometry types PIP can test, plus an open fallback (Point etc.). */
+/**
+ * The two areal GeoJSON geometry types PIP can test, plus an open fallback (Point etc.).
+ */
 export interface GeojsonPolygon {
 	type: "Polygon"
-	/** `[outerRing, hole1, hole2, …]` — each ring a closed list of positions. */
+	/**
+	 * `[outerRing, hole1, hole2, …]` — each ring a closed list of positions.
+	 */
 	coordinates: GeojsonPosition[][]
 }
 

package/geonames-aliases.ts

@@ -36,16 +36,115 @@ import { isOfficialLanguage } from "@mailwoman/codex/country"
  */
 export const GEONAMES_ID_BASE = 9_000_000_000_000
 
-/** Per-country progress for the ingest — one event per country dump processed (or skipped). */
+/**
+ * Per-country progress for the ingest — one event per country dump processed (or skipped).
+ */
 export interface GeonamesIngestProgress {
-	/** ISO 3166-1 alpha-2 code. */
+	/**
+	 * ISO 3166-1 alpha-2 code.
+	 */
 	country: string
-	/** Populated places ingested from this country's dump (0 when skipped). */
+	/**
+	 * Populated places ingested from this country's dump (0 when skipped).
+	 */
 	places: number
-	/** True when the country's `<CC>.txt` dump was missing — the country is skipped, not fatal. */
+	/**
+	 * True when the country's `<CC>.txt` dump was missing — the country is skipped, not fatal.
+	 */
 	skipped: boolean
 }
 
+/**
+ * One spelling's language attribution, as reconciled across every alternate-names row that carries it.
+ */
+interface V2Alias {
+	language: string
+	privateuse: string
+	official: number
+}
+
+/**
+ * Parse a country's alternateNamesV2 file into `geonameid -> spelling -> attribution`, restricted to the populated
+ * places (`P`) present in `lines`.
+ */
+function parseAlternateNamesV2(v2File: string, cc: string, lines: string[]): Map<number, Map<string, V2Alias>> {
+	const wanted = new Set<number>()
+
+	for (const line of lines) {
+		const f = line.split("\t")
+
+		if (f[6] === "P") {
+			wanted.add(Number(f[0]))
+		}
+	}
+
+	const v2 = new Map<number, Map<string, V2Alias>>()
+
+	// V2 columns (0-indexed): 1 geonameid, 2 isolanguage, 3 name, 4 isPreferredName, 5 isShortName,
+	// 6 isColloquial, 7 isHistoric, 8 from, 9 to.
+	//
+	// Two passes, because historic-ness is a fact about the NAME, not the row: GeoNames splits one
+	// spelling across rows — Malabo carries "Santa Isabel" as (es, unflagged) AND as (no-language,
+	// isHistoric=1, to=1973). Officialness must see the flags from EVERY row for the spelling, or the
+	// colonial-era name sails through on the language-tagged row (the #936 review's Malabo finding).
+	// Do NOT gate on isPreferredName instead — it's sparse annotation, not a signal (Turku's sv "Åbo"
+	// is unflagged; FI has 1,746 flags across the whole dump).
+	const v2Lines = readFileSync(v2File, "utf8").split("\n")
+	const historicNames = new Set<string>()
+
+	for (const line of v2Lines) {
+		if (!line) continue
+		const f = line.split("\t")
+
+		if (f[6] === "1" || f[7] === "1" || (f[9] ?? "").trim() !== "") {
+			const alt = (f[3] ?? "").trim()
+
+			if (alt && wanted.has(Number(f[1]))) {
+				historicNames.add(`${f[1]}|${alt}`)
+			}
+		}
+	}
+
+	for (const line of v2Lines) {
+		if (!line) continue
+		const f = line.split("\t")
+		const gid = Number(f[1])
+
+		if (!wanted.has(gid)) continue
+		const lang = f[2] ?? ""
+
+		// ISO 639 codes are 2-3 letters; GeoNames' pseudo-codes (post, link, iata, wkdt, …) are 4+.
+		if (!/^[a-z]{2,3}$/.test(lang)) continue
+		const alt = (f[3] ?? "").trim()
+
+		if (!alt) continue
+		const preferred = f[4] === "1"
+		const official = !historicNames.has(`${gid}|${alt}`) && isOfficialLanguage(cc, lang) ? 1 : 0
+		let byName = v2.get(gid)
+
+		if (!byName) {
+			v2.set(gid, (byName = new Map()))
+		}
+
+		const prev = byName.get(alt)
+
+		if (!prev) {
+			byName.set(alt, { language: lang, privateuse: preferred ? "preferred" : "", official })
+		} else {
+			if (official && !prev.official) {
+				prev.language = lang
+				prev.official = 1
+			}
+
+			if (preferred && !prev.privateuse) {
+				prev.privateuse = "preferred"
+			}
+		}
+	}
+
+	return v2
+}
+
 /**
  * Fold the GeoNames `P`-class places (+ their Latin alt-names) for `countries` into `db`'s `spr` / `names` /
  * `place_population` tables. Returns the total places ingested.
@@ -82,18 +181,23 @@ export function ingestGeonamesAliases(
 	// Latin-only, no bracket/paren noise GeoNames packs into `alternatenames` ("(( Karis Landskommun ))",
 	// airport codes), 2–60 chars, at least one letter (drops bare postcodes/numbers).
 	const LATIN_NAME = /^[\p{Script=Latin}\p{M}\s\-'.]{2,60}$/u
+
 	const clean = (s: string): string | null => {
 		const t = s.trim()
 
 		return t && LATIN_NAME.test(t) && /\p{L}/u.test(t) ? t : null
 	}
+
 	const sprInsert = db.prepare(
 		`INSERT OR REPLACE INTO spr (id, parent_id, name, placetype, country, latitude, longitude, min_latitude, min_longitude, max_latitude, max_longitude, is_current, is_deprecated, is_ceased, is_superseded, is_superseding, lastmodified) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
 	)
+
 	const namesInsert = db.prepare(
 		`INSERT INTO names (id, name, placetype, country, language, privateuse, official, lastmodified) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
 	)
+
 	const populationInsert = db.prepare(`INSERT OR REPLACE INTO place_population (id, population) VALUES (?, ?)`)
+
 	// #267 admin linkage: ancestor rows (locality→region→country) so parentID scoping + adminCoherence reach
 	// the gap countries. Only used for a country in opts.adminForCountries.
 	const ancestorInsert = db.prepare(
@@ -123,8 +227,10 @@ export function ingestGeonamesAliases(
 
 		if (!existsSync(file)) {
 			report({ country: cc, places: 0, skipped: true }, file)
+
 			continue
 		}
+
 		let nc = 0
 		// #267: add A-class admin + ancestry only for the gap countries this country is in (never the EU set).
 		const addAdmin = opts?.adminForCountries?.has(cc) ?? false
@@ -136,81 +242,7 @@ export function ingestGeonamesAliases(
 		// dump repeats one spelling under several languages ("Åbo" sv/da/no); the merged tag is official /
 		// preferred if ANY qualifying row is.
 		const v2File = opts?.alternateDir ? join(opts.alternateDir, `${cc}.txt`) : undefined
-		let v2: Map<number, Map<string, { language: string; privateuse: string; official: number }>> | undefined
-
-		if (v2File && existsSync(v2File)) {
-			const wanted = new Set<number>()
-
-			for (const line of lines) {
-				const f = line.split("\t")
-
-				if (f[6] === "P") {
-					wanted.add(Number(f[0]))
-				}
-			}
-			v2 = new Map()
-
-			// V2 columns (0-indexed): 1 geonameid, 2 isolanguage, 3 name, 4 isPreferredName, 5 isShortName,
-			// 6 isColloquial, 7 isHistoric, 8 from, 9 to.
-			//
-			// Two passes, because historic-ness is a fact about the NAME, not the row: GeoNames splits one
-			// spelling across rows — Malabo carries "Santa Isabel" as (es, unflagged) AND as (no-language,
-			// isHistoric=1, to=1973). Officialness must see the flags from EVERY row for the spelling, or the
-			// colonial-era name sails through on the language-tagged row (the #936 review's Malabo finding).
-			// Do NOT gate on isPreferredName instead — it's sparse annotation, not a signal (Turku's sv "Åbo"
-			// is unflagged; FI has 1,746 flags across the whole dump).
-			const v2Lines = readFileSync(v2File, "utf8").split("\n")
-			const historicNames = new Set<string>()
-
-			for (const line of v2Lines) {
-				if (!line) continue
-				const f = line.split("\t")
-
-				if (f[6] === "1" || f[7] === "1" || (f[9] ?? "").trim() !== "") {
-					const alt = (f[3] ?? "").trim()
-
-					if (alt && wanted.has(Number(f[1]))) {
-						historicNames.add(`${f[1]}|${alt}`)
-					}
-				}
-			}
-
-			for (const line of v2Lines) {
-				if (!line) continue
-				const f = line.split("\t")
-				const gid = Number(f[1])
-
-				if (!wanted.has(gid)) continue
-				const lang = f[2] ?? ""
-
-				// ISO 639 codes are 2-3 letters; GeoNames' pseudo-codes (post, link, iata, wkdt, …) are 4+.
-				if (!/^[a-z]{2,3}$/.test(lang)) continue
-				const alt = (f[3] ?? "").trim()
-
-				if (!alt) continue
-				const preferred = f[4] === "1"
-				const official = !historicNames.has(`${gid}|${alt}`) && isOfficialLanguage(cc, lang) ? 1 : 0
-				let byName = v2.get(gid)
-
-				if (!byName) {
-					v2.set(gid, (byName = new Map()))
-				}
-				const prev = byName.get(alt)
-
-				if (!prev) {
-					byName.set(alt, { language: lang, privateuse: preferred ? "preferred" : "", official })
-				} else {
-					if (official && !prev.official) {
-						prev.language = lang
-						prev.official = 1
-					}
-
-					if (preferred && !prev.privateuse) {
-						prev.privateuse = "preferred"
-					}
-				}
-			}
-		}
+		const v2 = v2File && existsSync(v2File) ? parseAlternateNamesV2(v2File, cc, lines) : undefined
 
 		// #267 admin pre-pass (gap countries): fold the country (PCLI) + regions (ADM1), self+ancestry them, and
 		// build the admin1→region map the localities link through. Point bbox (GeoNames gives a centroid only).
@@ -287,6 +319,7 @@ export function ingestGeonamesAliases(
 					ancestorInsert.run(nid, countryID, "country")
 				}
 			}
+
 			const seen = new Set([name])
 
 			const tags = v2?.get(Number(f[0]))
@@ -301,16 +334,20 @@ export function ingestGeonamesAliases(
 					namesInsert.run(nid, alt, "locality", cc, tag?.language ?? "", tag?.privateuse ?? "", tag?.official ?? 0, 0)
 				}
 			}
+
 			const pop = Number(f[14]) || 0
 
 			if (pop > 0) {
 				populationInsert.run(nid, pop)
 			}
+
 			nc++
 		}
+
 		report({ country: cc, places: nc, skipped: false })
 		total += nc
 	}
+
 	db.exec("COMMIT")
 
 	return total

package/geonames-postal.ts

@@ -38,6 +38,12 @@ import { existsSync, readFileSync } from "node:fs"
 import { join } from "node:path"
 import type { DatabaseSync } from "node:sqlite"
 
+/**
+ * Column count of a GeoNames postal-code TSV row. Short rows are truncated or blank and are skipped. See the
+ * allCountries.zip readme for the field list.
+ */
+const GEONAMES_POSTAL_COLUMNS = 11
+
 /**
  * Synthetic id base for GeoNames-POSTAL rows — its own namespace above the alias fold's {@link GEONAMES_ID_BASE} (9e12)
  * allocation so all four sources (WOF, Overture, GeoNames-alias, GeoNames-postal) coexist collision-free in a combined
@@ -51,15 +57,21 @@ export const GEONAMES_POSTAL_ID_BASE = 9_500_000_000_000
  * `"11-041"` → `"11041"`, `"AD500"` → `"AD500"`.
  */
 export function normalizePostcodeName(raw: string): string {
-	return raw.replace(/[^\p{L}\p{N}]/gu, "")
+	return raw.replaceAll(/[^\p{L}\p{N}]/gu, "")
 }
 
 export interface GeonamesPostalIngestResult {
-	/** Distinct postcodes inserted across all countries. */
+	/**
+	 * Distinct postcodes inserted across all countries.
+	 */
 	inserted: number
-	/** Per-country distinct-postcode counts. */
+	/**
+	 * Per-country distinct-postcode counts.
+	 */
 	byCountry: Record<string, number>
-	/** Countries whose `<CC>.txt` was missing under the postal dir (skipped, reported). */
+	/**
+	 * Countries whose `<CC>.txt` was missing under the postal dir (skipped, reported).
+	 */
 	missing: string[]
 }
 
@@ -77,6 +89,7 @@ export function ingestGeonamesPostal(
 	const sprInsert = db.prepare(
 		`INSERT OR REPLACE INTO spr (id, parent_id, name, placetype, country, latitude, longitude, min_latitude, min_longitude, max_latitude, max_longitude, is_current, is_deprecated, is_ceased, is_superseded, is_superseding, lastmodified) VALUES (?, -1, ?, 'postalcode', ?, ?, ?, ?, ?, ?, ?, 1, 0, 0, 0, 0, 0)`
 	)
+
 	const namesInsert = db.prepare(
 		`INSERT INTO names (id, name, placetype, country, language, lastmodified) VALUES (?, ?, 'postalcode', ?, '', 0)`
 	)
@@ -92,18 +105,21 @@ export function ingestGeonamesPostal(
 
 		if (!existsSync(file)) {
 			missing.push(cc)
+
 			console.error(
 				`  GeoNames postal ${cc}: ${file} missing — download from download.geonames.org/export/zip/${cc}.zip; skipped`
 			)
+
 			continue
 		}
+
 		// Group member settlement points per NORMALIZED code; remember one display form.
 		const members = new Map<string, { display: string; pts: Array<[number, number]> }>()
 
 		for (const line of readFileSync(file, "utf8").split("\n")) {
 			const cols = line.split("\t")
 
-			if (cols.length < 11) continue
+			if (cols.length < GEONAMES_POSTAL_COLUMNS) continue
 			const display = cols[1]!.trim()
 			const name = normalizePostcodeName(display)
 			const lat = Number(cols[9])
@@ -132,6 +148,7 @@ export function ingestGeonamesPostal(
 					best = p
 				}
 			}
+
 			const id = nextID++
 			sprInsert.run(id, name, cc, best[0], best[1], best[0], best[1], best[0], best[1])
 			namesInsert.run(id, name, cc)
@@ -139,10 +156,13 @@ export function ingestGeonamesPostal(
 			if (m.display !== name) {
 				namesInsert.run(id, m.display, cc)
 			}
+
 			inserted++
 		}
+
 		db.exec("COMMIT")
 		byCountry[cc] = members.size
+
 		console.error(`  GeoNames postal ${cc}: ${members.size.toLocaleString()} distinct codes (medoid centroids)`)
 	}