@mailwoman/resolver-wof-sqlite 8.6.0 → 9.1.0

package/fst-serialize.ts

@@ -18,11 +18,23 @@
  *
  *   EDGE TABLE [edgeCount × 8 bytes] stringIdx u32 index into string table targetState u32
  *
- *   PLACE TABLE [placeCount × 56 bytes] wofID u32 placetypeIdx u8 index into PLACETYPE_ORDER chainLen
- *   u8 0..8 _pad u16 nameIdx u32 index into string table importance f32 Wikipedia importance [0,1]
- *   (V2); was population u32 (V1) lat f32 lon f32 chain [u32; 8] parent chain (unused slots = 0)
+ *   PLACE TABLE [placeCount × 60 bytes at V5, 56 below] wofID u32 placetypeIdx u8 index into
+ *   PLACETYPE_ORDER chainLen u8 0..8 crossCountryBranches u8 (header flags bit0 gates the read)
+ *   placeFlags u8 (V5; bit0 = encyclopedic present) nameIdx u32 index into string table referential f32
+ *   population-anchored likelihood [0,1] — was the conflated `importance` (V2–V4), was population u32
+ *   (V1) lat f32 lon f32 chain [u32; 8] parent chain (unused slots = 0) encyclopedic f32 (V5 only;
+ *   read only when placeFlags bit0 is set)
+ *
+ *   THE V5 BUMP IS THE TWO-SCORE SPLIT (ROAD_TO_V9 §2 R1). Through V4 one float carried whichever score
+ *   the source database held, and nothing in the bytes said which — so a reader could not tell a
+ *   population proxy from a Wikipedia score. V5 names the ranking score `referential` and gives the
+ *   encyclopedic signal its own slot plus a PER-PLACE presence bit, because most places have no
+ *   Wikipedia article and a 0 there would be a fact nobody recorded. `fst-freshness.ts` reports every
+ *   V4-and-below artifact as format-stale for exactly this reason: its single float is unattributable.
  */
 
+import { tryParsingJSON } from "@mailwoman/core/objects"
+
 import type { FSTNode } from "./fst-matcher.ts"
 import { FSTMatcher } from "./fst-matcher.ts"
 import type { FSTProvenance, PlaceEntry, PlacetypeID } from "./fst-types.ts"
@@ -48,6 +60,34 @@ const NARROW_STATE_ENTRY_SIZE = 12
  */
 const VERSION_WITH_METADATA = 3
 
+/**
+ * Format version that split the single `importance` float into `referential` + `encyclopedic`, growing the place entry
+ * from 56 to 60 bytes and claiming the previously-reserved `pp+7` byte as {@link PLACE_FLAG_HAS_ENCYCLOPEDIC}.
+ */
+const VERSION_TWO_SCORE_SPLIT = 5
+
+/**
+ * Place-entry size in bytes at or above {@link VERSION_TWO_SCORE_SPLIT}.
+ */
+const SPLIT_PLACE_ENTRY_SIZE = 60
+
+/**
+ * Place-entry size in bytes below {@link VERSION_TWO_SCORE_SPLIT}.
+ */
+const LEGACY_PLACE_ENTRY_SIZE = 56
+
+/**
+ * Byte offset of the encyclopedic float inside a v5 place entry — immediately after the 8-slot parent chain.
+ */
+const ENCYCLOPEDIC_OFFSET = 56
+
+/**
+ * `placeFlags` bit 0 (byte `pp+7`, v5+): this place carries an encyclopedic score. Per-PLACE rather than per-file
+ * because absence is the common case — roughly 89% of the 2026-08-05 gazetteer has no Wikipedia article — and a
+ * file-level flag would force every one of those rows to claim a 0 it never had.
+ */
+const PLACE_FLAG_HAS_ENCYCLOPEDIC = 1
+
 /**
  * File magic. A reader rejects anything not starting with these four bytes before parsing further.
  */
@@ -56,7 +96,14 @@ const MAGIC = Buffer.from("FST\0", "ascii")
 /**
  * Format version this serializer emits. See {@link VERSION_WIDE_STATE_COUNTERS} for what each bump changed.
  */
-const VERSION = 4
+const VERSION = 5
+
+/**
+ * The format version this tree WRITES, published so a freshness guard can call an older artifact format-stale without
+ * re-typing the number. Mirrors `REQUIRED_PAIR_INDEX_SCHEMA`'s role for PIX1: one constant, so a version bump cannot be
+ * noticed by some checkers and not others. See `fst-freshness.ts`.
+ */
+export const FST_FORMAT_VERSION = VERSION
 
 /**
  * Fixed header size in bytes: magic, version, and the section offsets that follow it.
@@ -74,9 +121,9 @@ const STATE_ENTRY_SIZE = 16
 const EDGE_ENTRY_SIZE = 8
 
 /**
- * Place-table entry: the place id, its placetype, coordinates, and importance.
+ * Place-table entry at the version this tree WRITES: the place id, its placetype, coordinates, and both scores.
  */
-const PLACE_ENTRY_SIZE = 56
+const PLACE_ENTRY_SIZE = SPLIT_PLACE_ENTRY_SIZE
 
 /**
  * Longest ancestry chain stored per place. Deeper hierarchies are truncated at the leaf end, since the specific end of
@@ -237,11 +284,14 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 			buf.writeUInt32LE(place.wofID, pp)
 			buf.writeUInt8(placetypeToIdx.get(place.placetype) ?? 0, pp + 4)
 			buf.writeUInt8(chainLen, pp + 5)
-			// Former _pad: byte 0 = crossCountryBranches (header flags bit0 gates the read), byte 1 reserved.
+			// Former _pad: byte 0 = crossCountryBranches (header flags bit0 gates the read), byte 1 = v5 placeFlags.
 			buf.writeUInt8(hasAmbiguity ? Math.min(place.crossCountryBranches ?? 0, 255) : 0, pp + 6)
-			buf.writeUInt8(0, pp + 7)
+			// An absent encyclopedic score writes flag 0 AND a 0.0 float. The float is unread in that
+			// state, so absence can never surface as a score — the meaning-of-zero rule, in bytes.
+			const hasEncyclopedic = place.encyclopedic !== undefined
+			buf.writeUInt8(hasEncyclopedic ? PLACE_FLAG_HAS_ENCYCLOPEDIC : 0, pp + 7)
 			buf.writeUInt32LE(intern(place.name), pp + 8)
-			buf.writeFloatLE(place.importance, pp + 12)
+			buf.writeFloatLE(place.referential, pp + 12)
 			buf.writeFloatLE(place.lat, pp + 16)
 			buf.writeFloatLE(place.lon, pp + 20)
 
@@ -249,6 +299,8 @@ export function serializeFST(matcher: FSTMatcher, provenance?: FSTProvenance): B
 				buf.writeUInt32LE(ci < chainLen ? validChain[ci]! : 0, pp + 24 + ci * 4)
 			}
 
+			buf.writeFloatLE(hasEncyclopedic ? place.encyclopedic! : 0, pp + ENCYCLOPEDIC_OFFSET)
+
 			placeIdx++
 		}
 	}
@@ -271,6 +323,7 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 
 	if (version < 1 || version > VERSION) throw new Error(`FST version ${version} unsupported (expected 1..${VERSION})`)
 	const isV2 = version >= 2
+	const isSplit = version >= VERSION_TWO_SCORE_SPLIT
 	// flags bit0 (survey #4): place rows carry surface-ambiguity data in the former _pad byte.
 	const hasAmbiguity = (buf.readUInt16LE(6) & 1) === 1
 
@@ -303,6 +356,8 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 
 	// --- State table ---
 	const stateEntrySize = version >= VERSION_WIDE_STATE_COUNTERS ? WIDE_STATE_ENTRY_SIZE : NARROW_STATE_ENTRY_SIZE
+	// v5 grew the place entry by the encyclopedic float; v4-and-below files are read at the old stride.
+	const placeEntrySize = version >= VERSION_TWO_SCORE_SPLIT ? SPLIT_PLACE_ENTRY_SIZE : LEGACY_PLACE_ENTRY_SIZE
 	const stateTableStart = pos
 	const edgeTableStart = stateTableStart + stateCount * stateEntrySize
 	const placeTableStart = edgeTableStart + edgeCount * EDGE_ENTRY_SIZE
@@ -332,7 +387,7 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 		const places: PlaceEntry[] = new Array(placeCountForState)
 
 		for (let pi = 0; pi < placeCountForState; pi++) {
-			const pp = placeTableStart + (placeStart + pi) * PLACE_ENTRY_SIZE
+			const pp = placeTableStart + (placeStart + pi) * placeEntrySize
 			const chainLen = buf.readUInt8(pp + 5)
 			const parentChain: number[] = []
 
@@ -340,20 +395,30 @@ export function deserializeFST(buf: Buffer): FSTMatcher {
 				parentChain.push(buf.readUInt32LE(pp + 24 + ci * 4))
 			}
 
-			const rawImportance = isV2
+			// v1 stored a raw population u32 here; v2–v4 the conflated `importance` float; v5 the
+			// referential score. A v1 file's population is mapped through the SAME curve
+			// `referentialFromPopulation` uses, so its value is genuinely referential — the only
+			// generation of this format for which that can be said without reading the source database.
+			const referential = isV2
 				? buf.readFloatLE(pp + 12)
 				: Math.min(1, Math.log2(1 + buf.readUInt32LE(pp + 12) / 1000) / 14)
 
+			// Per-place presence bit (v5+). A v4-and-below file has no encyclopedic channel at all, so
+			// the field stays undefined rather than reading the reserved byte as a flag.
+			const hasEncyclopedic =
+				isSplit && (buf.readUInt8(pp + 7) & PLACE_FLAG_HAS_ENCYCLOPEDIC) === PLACE_FLAG_HAS_ENCYCLOPEDIC
+
 			places[pi] = {
 				wofID: buf.readUInt32LE(pp),
 				placetype: PLACETYPE_ORDER[buf.readUInt8(pp + 4)] ?? "locality",
 				name: strings[buf.readUInt32LE(pp + 8)]!,
-				importance: rawImportance,
+				referential,
 				lat: buf.readFloatLE(pp + 16),
 				lon: buf.readFloatLE(pp + 20),
 				parentChain,
 				// Header flags bit0 gates the read (survey #4): pre-ambiguity artifacts expose undefined.
 				...(hasAmbiguity ? { crossCountryBranches: buf.readUInt8(pp + 6) } : {}),
+				...(hasEncyclopedic ? { encyclopedic: buf.readFloatLE(pp + ENCYCLOPEDIC_OFFSET) } : {}),
 			}
 		}
 
@@ -378,7 +443,7 @@ export function readFSTProvenance(buf: Buffer): FSTProvenance | undefined {
 		const jsonLen = buf.readUInt32LE(provenanceOffset)
 		const jsonStr = buf.toString("utf8", provenanceOffset + 4, provenanceOffset + 4 + jsonLen)
 
-		return JSON.parse(jsonStr) as FSTProvenance
+		return tryParsingJSON<FSTProvenance>(jsonStr) ?? undefined
 	} catch {
 		return undefined
 	}

package/fst-types.ts

@@ -13,7 +13,25 @@ export interface PlaceEntry {
 	placetype: PlacetypeID
 	name: string
 	parentChain: number[]
-	importance: number
+	/**
+	 * REFERENTIAL likelihood in [0, 1] — population-anchored (`referentialFromPopulation`), and the ONLY score the
+	 * decoder bias is allowed to read (ROAD_TO_V9 §2, ratified 2026-08-06).
+	 *
+	 * This field was called `importance` through format v4, where it carried whichever score the source database happened
+	 * to hold: the population proxy on a database with no `place_importance` table (which is every shipped
+	 * `fst-per-locale` binary), the Wikipedia score where the concordance join landed otherwise. The rename is the point
+	 * — a v4 artifact's value is a CONFLATION that cannot be told apart after the fact, which is why `fst-freshness.ts`
+	 * reports anything below {@link FST_FORMAT_VERSION} as format-stale rather than reading it as referential.
+	 */
+	referential: number
+	/**
+	 * Encyclopedic (Wikipedia) importance in [0, 1], fan-out-guarded per #1497. Carried for consumers that want to
+	 * DISPLAY salience; never read by the decoder or by any ranking.
+	 *
+	 * `undefined` = this place has no encyclopedic signal, or the artifact predates format 5. NEVER conflate either with
+	 * 0 — the meaning-of-zero rule; roughly 89% of the 2026-08-05 gazetteer's rows have no Wikipedia article at all.
+	 */
+	encyclopedic?: number
 	lat: number
 	lon: number
 	/**
@@ -64,8 +82,41 @@ export interface FSTProvenance {
 	placeCount: number
 	edgeCount: number
 	nameInsertions: number
+	/**
+	 * How many places carried a non-zero REFERENTIAL score at build time. Named `importanceMatches` for stamp
+	 * compatibility with every artifact written before the two-score split — renaming the JSON key would make every
+	 * existing stamp unreadable, and the number means the same thing it always did on a population-built artifact.
+	 */
 	importanceMatches: number
+	/**
+	 * How many places carried an ENCYCLOPEDIC score at build time. `undefined` on a pre-split build — which is not the
+	 * same as 0 (a v5 build against a population-only database), so the freshness report says the two in different
+	 * words.
+	 */
+	encyclopedicMatches?: number
+	/**
+	 * How the builder obtained its two scores — an {@link ImportanceSplitSource}. Recorded so an artifact states, in its
+	 * own provenance, whether its encyclopedic channel is real, reconstructed from a legacy conflated column, or absent.
+	 */
+	importanceSource?: string
 	sourceDB?: string
+	/**
+	 * MD5 of the source database's bytes at build time — the artifact's link to the gazetteer it is a projection of.
+	 *
+	 * `sourceDB` records the PATH, which is exactly the field that cannot change when the bytes behind it do: the admin
+	 * DB is a sealed readonly artifact that a rebuild REPLACES in place, so every FST built before the 2026-08-04 swap
+	 * still names the current file and none of them was built from it. Compared by `fst-freshness.ts`.
+	 *
+	 * `undefined` = built before the stamp existed (every artifact predating 2026-08-05). NEVER conflate that with "built
+	 * from a database whose md5 is unknown" — the freshness check reports the two in different words.
+	 */
+	sourceDBMD5?: string
+	/**
+	 * Byte size of the source database at build time. Not redundant with {@link FSTProvenance.sourceDBMD5}: it survives a
+	 * truncated source and it is what makes a staleness warning legible — "5,273,722,880 → 5,372,076,032" names the
+	 * rebuild, a hex delta does not.
+	 */
+	sourceDBBytes?: number
 	modelCardVersion?: string
 	/**
 	 * Degenerate-surface curation policy applied at build time (absent = uncurated build).
@@ -79,6 +130,12 @@ export interface FSTProvenance {
 
 export interface BuildFSTOpts {
 	dbPath: string
+	/**
+	 * Pre-computed identity of `dbPath` to stamp into provenance. Omit and the builder reads it via
+	 * `readWOFSourceIdentity` (sidecar-cached). Supply it when the digest is already in hand, or when the caller is
+	 * building from something whose identity it defines itself.
+	 */
+	sourceIdentity?: { md5: string; bytes: number }
 	countries?: string[]
 	placetypes?: PlacetypeID[]
 	languages?: string[]

package/fts.ts

@@ -123,6 +123,18 @@ export const PLACE_BBOX_TABLE = "place_bbox"
  */
 export const PLACE_POPULATION_TABLE = "place_population"
 
+/**
+ * Name of the auxiliary table holding the two salience scores per place — `referential` (population-anchored, the
+ * ranking backbone) and `encyclopedic` (the Wikipedia join, NULL when there is no article). Built by `mailwoman
+ * gazetteer importance`; schema and derivations in `place-importance-schema.ts`.
+ *
+ * The lookup reads ONLY `encyclopedic` from it, and only to CARRY the value onto the result — referential is derived
+ * from the population already joined, and no ORDER BY anywhere touches this table (ROAD_TO_V9 §2). Sparse and
+ * schema-versioned: a pre-split gazetteer has this table with a single conflated `importance` column instead, which the
+ * lookup's column probe deliberately refuses to read.
+ */
+export const PLACE_IMPORTANCE_TABLE = "place_importance"
+
 /**
  * Counters for a single `buildPlaceSearchFTS` run. Exposed so callers (CLI, lazy-build) can render progress to the
  * user.

package/geo.ts

@@ -10,17 +10,20 @@
  *   ray-cast PIP a ~30-line one — both plenty fast for the post-fetch passes (we operate on ≤ a few
  *   hundred candidates per query, not the whole 142k-row corpus).
  *
- *   The PIP implementation here is the CANONICAL port of the even-odd ray cast that previously lived
- *   only in Python (`scripts/eval/pip-containment.py`, with a second copy in
- *   `scripts/build-postcode-locality.ts`). Keep the three in sync if the algorithm ever changes —
- *   the eval-side Python copies grade the same containment truth this one resolves with.
+ *   The even-odd ray cast lives in `@mailwoman/spatial` and is re-exported below, so the resolver,
+ *   the reverse-geocoder and the gazetteer pipeline share one definition. `scripts/eval/pip-containment.py`
+ *   grades the same containment truth and has to be matched BY HAND if the algorithm changes — it is
+ *   the one copy no import can reach.
  *
  *   The R*Tree index name + schema are centralized in `fts.ts` (alongside the FTS5 build).
  */
 
-// haversineKm is the canonical implementation in @mailwoman/spatial; re-exported so this package's
-// readers keep importing it from "./geo.ts" (the spatial dep is transitive via @mailwoman/resolver).
-export { haversineKm } from "@mailwoman/spatial"
+import { pointInPolygon } from "@mailwoman/spatial"
+
+// haversineKm and the point-in-polygon ray cast are implemented in @mailwoman/spatial, the math
+// home; re-exported so this package's readers keep importing them from "./geo.ts" (the spatial dep
+// is transitive via @mailwoman/resolver).
+export { haversineKm, pointInRing } from "@mailwoman/spatial"
 
 /**
  * WGS-84 degrees → radians.
@@ -82,42 +85,14 @@ export interface GeojsonMultiPolygon {
 export type GeojsonGeometry = GeojsonPolygon | GeojsonMultiPolygon | { type: string; coordinates?: unknown }
 
 /**
- * Ray-cast a point against ONE linear ring. Standard even-odd crossing count: shoot a ray along +lon and toggle on
- * every edge crossing. Points exactly on an edge are implementation-defined (either side is acceptable for geocoding —
- * admin boundaries are DP-simplified anyway).
- */
-export function pointInRing(lon: number, lat: number, ring: readonly GeojsonPosition[]): boolean {
-	let inside = false
-	const n = ring.length
-
-	for (let i = 0, j = n - 1; i < n; j = i++) {
-		const xi = ring[i]![0]
-		const yi = ring[i]![1]
-		const xj = ring[j]![0]
-		const yj = ring[j]![1]
-
-		if (yi > lat !== yj > lat && lon < ((xj - xi) * (lat - yi)) / (yj - yi) + xi) {
-			inside = !inside
-		}
-	}
-
-	return inside
-}
-
-/**
- * Even-odd containment over a polygon's ring list (`[outer, hole1, …]`) — being inside an odd number of rings means
- * inside the polygon, which handles holes without ring-orientation rules.
+ * Even-odd containment over a polygon's ring list (`[outer, hole1, …]`).
+ *
+ * Named alias for `@mailwoman/spatial`'s {@link pointInPolygon}, kept because this package's readers and the gazetteer
+ * pipeline import `pointInPolygonRings` by name and the "rings" spelling is what makes the ring-list argument obvious
+ * at those call sites.
  */
 export function pointInPolygonRings(lon: number, lat: number, rings: readonly GeojsonPosition[][]): boolean {
-	let inside = false
-
-	for (const ring of rings) {
-		if (pointInRing(lon, lat, ring)) {
-			inside = !inside
-		}
-	}
-
-	return inside
+	return pointInPolygon(lon, lat, rings)
 }
 
 /**

package/geonames-aliases.ts

@@ -24,11 +24,14 @@
  *   (TSV).
  */
 
-import { existsSync, readFileSync } from "node:fs"
-import { join } from "node:path"
+import { existsSync } from "node:fs"
 import type { DatabaseSync } from "node:sqlite"
 
 import { isOfficialLanguage } from "@mailwoman/codex/country"
+import { join } from "path-ts"
+import { TSVSpliterator } from "spliterator"
+
+import { GEONAMES_POSTAL_ID_BASE } from "./geonames-postal.ts"
 
 /**
  * Synthetic id base for GeoNames-sourced rows (#743/#193) — above Overture's 8e12 so the three sources (WOF real ids,
@@ -36,6 +39,47 @@ import { isOfficialLanguage } from "@mailwoman/codex/country"
  */
 export const GEONAMES_ID_BASE = 9_000_000_000_000
 
+/**
+ * The four tables the alias fold writes into the range it owns. The purge and the ingest must agree on this list — a
+ * table written but not purged is exactly the #1514 defect.
+ */
+const FOLD_OWNED_TABLES = ["spr", "names", "place_population", "ancestors"] as const
+
+/**
+ * Clear everything the alias fold owns — `[GEONAMES_ID_BASE, GEONAMES_POSTAL_ID_BASE)` across {@link
+ * FOLD_OWNED_TABLES}
+ * — so a fold's output is a function of its country list and dumps ALONE, never of what the DB happened to hold first.
+ * Returns the rows removed per table.
+ *
+ * This exists because the synthetic id is a POSITION (`GEONAMES_ID_BASE + n`, counted across the country list in
+ * order), not a derivation from the geonameid: change the list, its order, or a dump's contents and every subsequent id
+ * shifts. Without the purge, a second fold overwrote the `spr` PREFIX it reached (`INSERT OR REPLACE`) while its
+ * `names`/`ancestors` rows merely appended (bare `INSERT`) and `place_population` skipped unpopulated places entirely —
+ * so the previous run's names, ancestry and populations stayed bound to ids now describing other places.
+ *
+ * Measured on the live 2026-08-05 artifact: a 14-country re-fold over the 161-country fold baked into
+ * `admin-global-priority.db` put 522,184 of 2,110,096 name rows in the range (24.7 %) on a place from a different
+ * country. Gaborone/BW at id 9000000121151 became Aichegg/AT and kept all 26 of its names; Kinshasa's 16,000,000
+ * population landed on a Lithuanian hamlet.
+ *
+ * The upper bound is NOT the end of the id space. Each later shard owns a range above this one — GeoNames-postal @
+ * 9.5e12, NL-PC6 @ 9.6e12, Code-Point @ 9.7e12, NI @ 9.8e12 — and a purge that ran past {@link GEONAMES_POSTAL_ID_BASE}
+ * would delete them.
+ */
+export function purgeGeonamesAliasRange(db: DatabaseSync): Record<string, number> {
+	const removed: Record<string, number> = {}
+
+	for (const table of FOLD_OWNED_TABLES) {
+		const result = db
+			.prepare(`DELETE FROM ${table} WHERE id >= ? AND id < ?`)
+			.run(GEONAMES_ID_BASE, GEONAMES_POSTAL_ID_BASE)
+
+		removed[table] = Number(result.changes)
+	}
+
+	return removed
+}
+
 /**
  * Per-country progress for the ingest — one event per country dump processed (or skipped).
  */
@@ -65,19 +109,13 @@ interface V2Alias {
 
 /**
  * Parse a country's alternateNamesV2 file into `geonameid -> spelling -> attribution`, restricted to the populated
- * places (`P`) present in `lines`.
+ * places (`P`) in `wanted`.
  */
-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]))
-		}
-	}
-
+async function parseAlternateNamesV2(
+	v2File: string,
+	cc: string,
+	wanted: ReadonlySet<number>
+): Promise<Map<number, Map<string, V2Alias>>> {
 	const v2 = new Map<number, Map<string, V2Alias>>()
 
 	// V2 columns (0-indexed): 1 geonameid, 2 isolanguage, 3 name, 4 isPreferredName, 5 isShortName,
@@ -89,13 +127,13 @@ function parseAlternateNamesV2(v2File: string, cc: string, lines: string[]): Map
 	// 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")
+	//
+	// Both passes STREAM the file rather than sharing one materialized array: NO's V2 dump is 33 MB,
+	// and a second read off the page cache costs less than holding half a million line strings.
+	// `header: false` — the dump is headerless.
 	const historicNames = new Set<string>()
 
-	for (const line of v2Lines) {
-		if (!line) continue
-		const f = line.split("\t")
-
+	for await (const f of TSVSpliterator.fromAsync(v2File, { header: false })) {
 		if (f[6] === "1" || f[7] === "1" || (f[9] ?? "").trim() !== "") {
 			const alt = (f[3] ?? "").trim()
 
@@ -105,9 +143,7 @@ function parseAlternateNamesV2(v2File: string, cc: string, lines: string[]): Map
 		}
 	}
 
-	for (const line of v2Lines) {
-		if (!line) continue
-		const f = line.split("\t")
+	for await (const f of TSVSpliterator.fromAsync(v2File, { header: false })) {
 		const gid = Number(f[1])
 
 		if (!wanted.has(gid)) continue
@@ -153,7 +189,7 @@ function parseAlternateNamesV2(v2File: string, cc: string, lines: string[]): Map
  * caller MUST rebuild `place_search` afterward (`buildPlaceSearchFTS(db, { drop: true })`) for the new names to reach
  * the candidate build's alias pass.
  */
-export function ingestGeonamesAliases(
+export async function ingestGeonamesAliases(
 	db: DatabaseSync,
 	countries: string[],
 	geonamesDir: string,
@@ -177,7 +213,7 @@ export function ingestGeonamesAliases(
 		 */
 		alternateDir?: string
 	}
-): number {
+): Promise<number> {
 	// 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
@@ -222,6 +258,10 @@ export function ingestGeonamesAliases(
 	let total = 0
 	db.exec("BEGIN")
 
+	// #1514: clear the range before writing it. Inside the transaction, so a fold that throws leaves the
+	// DB as it found it rather than half-purged. See purgeGeonamesAliasRange for why the ids demand this.
+	purgeGeonamesAliasRange(db)
+
 	for (const cc of countries) {
 		const file = join(geonamesDir, `${cc}.txt`)
 
@@ -234,15 +274,43 @@ export function ingestGeonamesAliases(
 		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
+		const v2File = opts?.alternateDir ? join(opts.alternateDir, `${cc}.txt`) : undefined
+		const readV2 = Boolean(v2File && existsSync(v2File))
+
+		// Survey pass. The dump is STREAMED — NO's is 71 MB and only the caller knows which country
+		// comes next — so what a later pass needs has to be collected here rather than re-scanned off a
+		// materialized array. Two things qualify, and both are small: the P-class geonameid set the V2
+		// decoration is restricted to, and the handful of A-class rows the admin pre-pass writes (one
+		// PCL* + the ADM1s). Everything else is re-read in the emit pass below. Neither is wanted
+		// without V2 tags or admin, and then the pass is skipped rather than read for nothing.
+		//
 		// GeoNames dump columns (0-indexed): 0 geonameid, 1 name, 2 asciiname, 3 alternatenames, 4 lat, 5 lon,
 		// 6 feature_class, 7 feature_code, 10 admin1 code, 14 pop.
-		const lines = readFileSync(file, "utf8").split("\n")
+		//
+		// `header: false` — the dump is headerless, so row 1 is a place, not column names.
+		const wanted = new Set<number>()
+		const adminRows: string[][] = []
+
+		if (readV2 || addAdmin) {
+			for await (const f of TSVSpliterator.fromAsync(file, { header: false })) {
+				if (f[6] === "P") {
+					if (readV2) {
+						wanted.add(Number(f[0]))
+					}
+
+					continue
+				}
+
+				if (addAdmin && f[6] === "A" && (f[7]?.startsWith("PCL") || (f[7] === "ADM1" && f[10]))) {
+					adminRows.push(f)
+				}
+			}
+		}
 
 		// #936: V2 tags for this country's P-class rows — geonameid → exact alias spelling → tag. The V2
 		// 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
-		const v2 = v2File && existsSync(v2File) ? parseAlternateNamesV2(v2File, cc, lines) : undefined
+		const v2 = readV2 ? await parseAlternateNamesV2(v2File!, cc, wanted) : 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).
@@ -250,10 +318,7 @@ export function ingestGeonamesAliases(
 		const adminMap = new Map<string, number>()
 
 		if (addAdmin) {
-			for (const line of lines) {
-				const f = line.split("\t")
-
-				if (f[6] !== "A") continue
+			for (const f of adminRows) {
 				const aname = clean(f[2] ?? "") ?? clean(f[1] ?? "")
 
 				if (!aname) continue
@@ -287,10 +352,8 @@ export function ingestGeonamesAliases(
 			}
 		}
 
-		for (const line of lines) {
-			if (!line) continue
-			const f = line.split("\t")
-
+		// Emit pass — a second stream over the same file, off the page cache the survey pass just warmed.
+		for await (const f of TSVSpliterator.fromAsync(file, { header: false })) {
 			if (f[6] !== "P") continue // populated places only
 			const lat = Number(f[4])
 			const lon = Number(f[5])
@@ -308,9 +371,14 @@ export function ingestGeonamesAliases(
 			sprInsert.run(nid, parentID, name, "locality", cc, lat, lon, lat, lon, lat, lon, 1, 0, 0, 0, 0, 0)
 			namesInsert.run(nid, name, "locality", cc, "", "", 0, 0)
 
-			if (addAdmin) {
-				ancestorInsert.run(nid, nid, "locality")
+			// The SELF row is unconditional (#1514). `populateAncestors` writes one for every spr row it
+			// sees, so a full build's freeze phase produces it either way — but the freeze does not run on
+			// the fold-on-copy path, and since the purge now clears this range the fold has to emit
+			// everything the closure would. Measured on the 161-country fold: 212,993 self rows, exactly the
+			// non-gap countries' localities, which is what the base artifact carried and a fold-on-copy lost.
+			ancestorInsert.run(nid, nid, "locality")
 
+			if (addAdmin) {
 				if (regionID >= 0) {
 					ancestorInsert.run(nid, regionID, "region")
 				}