@mailwoman/resolver-wof-sqlite 9.4.0 → 10.1.0

package/lib/candidate/{ancestors-sidecar.ts → ancestors/sidecar.ts}

@@ -7,7 +7,7 @@
 
 import type { DatabaseClient } from "@mailwoman/sqlite/client"
 
-import { placetypeDepth } from "#ancestry/index"
+import { placetypeDepth } from "#ancestry"
 import {
 	CANDIDATE_ANCESTOR_COLUMNS,
 	CANDIDATE_ANCESTOR_TABLE,
@@ -15,20 +15,15 @@ import {
 	createCandidateAncestorTable,
 	createCandidateIntervalTable,
 	MAX_ANCESTOR_DEPTH,
-} from "#candidate-ancestors-schema"
-import type { CandidateDatabase } from "#candidate-schema"
+} from "#candidate/ancestors/schema"
 import type { PlaceAttrs } from "#candidate/place-attrs"
+import type { CandidateDatabase } from "#candidate/schema"
 import type { WOFDatabase } from "#schema"
 
 /**
- * Pass 3b — the ancestors sidecar: closure rows + interval labels (candidate-ancestors-schema.ts owns the encoding
- * decision and the DAG/absence semantics). Reads the same source `ancestors` table the region stamp reads,
- * denormalizing each edge with the parent's name/key from `attrs`, streamed `ORDER BY id` so the clustered `(spr_id,
- * depth)` insert is sorted — the contiguous-leaves discipline of the candidate table itself.
- *
- * Excluded by policy: self rows, and placetypes outside the containment ladder (continent, empire, …: `placetypeDepth` 0)
- * — they discriminate nothing a consumer of this sidecar checks. An edge to a parent with no current `spr` row has no
- * name to denormalize; it is dropped and counted rather than stored blind.
+ * Build the ancestors sidecar (closure rows plus interval labels) from the source
+ * `ancestors` table, excluding self rows and placetypes outside the containment ladder.
+ * an edge to a parent with no current `spr` row is dropped and counted.
  */
 export async function buildAncestorsSidecar(ctx: {
 	src: DatabaseClient<WOFDatabase>
@@ -47,9 +42,8 @@ export async function buildAncestorsSidecar(ctx: {
 		`INSERT INTO ${CANDIDATE_ANCESTOR_TABLE} VALUES (${CANDIDATE_ANCESTOR_COLUMNS.map(() => "?").join(", ")})`
 	)
 
-	// The canonical-parent forest the interval labels are computed over. One parent per place — the
-	// depth-1 edge (finest containment tier, lowest ancestor id; the `regionOf` MIN-stability
-	// convention). ALL parents stay in the closure rows; only the interval tree canonicalizes.
+	// One parent per place (the finest containment tier, lowest ancestor id) canonicalizes the interval tree.
+	// All parents stay in the closure rows.
 	const canonicalParentOf = new Map<number, number>()
 	const childrenOf = new Map<number, number[]>()
 	const forest = new Set<number>()
@@ -58,15 +52,15 @@ export async function buildAncestorsSidecar(ctx: {
 	let ancestorPlaces = 0
 	let droppedParents = 0
 
-	// Per-child edge buffer; the stream below is grouped by child id, so each flush owns one place.
+	// The stream is grouped by child id, so each flush owns one place.
 	let childID = -1
 	let edges: Array<{ aid: number; apt: string }> = []
 
 	const flush = (): void => {
 		if (childID < 0 || !edges.length) return
 
-		// Deterministic nearest-first: containment depth descending, then ancestor id ascending —
-		// the FTS backend's `ancestorLineage` ordering, made stable across rebuilds.
+		// Deterministic nearest-first: containment depth descending, then ancestor id ascending,
+		// matching the FTS backend's `ancestorLineage` ordering across rebuilds.
 		edges.sort((a, b) => placetypeDepth(b.apt) - placetypeDepth(a.apt) || a.aid - b.aid)
 
 		if (edges.length > MAX_ANCESTOR_DEPTH) {
@@ -132,8 +126,8 @@ export async function buildAncestorsSidecar(ctx: {
 	flush()
 	out.exec("COMMIT")
 
-	// Interval labels: pre/post-order DFS over the canonical-parent forest. Root order and child
-	// order are id-ascending so the labels are stable across rebuilds of the same source.
+	// Interval labels are a pre/post-order DFS over the canonical-parent forest, with root
+	// and child order id-ascending so labels stay stable across rebuilds.
 	const preOf = new Map<number, number>()
 	const postOf = new Map<number, number>()
 
@@ -160,8 +154,8 @@ export async function buildAncestorsSidecar(ctx: {
 			if (kids && top.next < kids.length) {
 				const kid = kids[top.next++]!
 
-				// Each child holds exactly one canonical parent, so a labeled node here means the
-				// grouping upstream broke — skip rather than corrupt the numbering.
+				// Each child holds exactly one canonical parent, so a labeled node means upstream grouping broke.
+				// Skip rather than corrupt the numbering.
 				if (preOf.has(kid)) continue
 
 				preOf.set(kid, counter++)
@@ -173,9 +167,8 @@ export async function buildAncestorsSidecar(ctx: {
 		}
 	}
 
-	// A canonical-parent CYCLE (corrupt source ancestry) leaves its members unreachable from any
-	// root: they simply receive no label, and containment against them reads unverifiable — the
-	// absence semantics the schema module states. Counted so a jump is visible across rebuilds.
+	// A canonical-parent cycle leaves its members unreachable from any root,
+	// so they receive no label and containment against them reads unverifiable.
 	const cycleSkipped = forest.size - preOf.size
 
 	const insInterval = out.prepare(`INSERT INTO ${CANDIDATE_INTERVAL_TABLE} VALUES (?, ?, ?)`)

package/lib/candidate/country-display-names.ts

@@ -2,7 +2,6 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- * @file Pass 1b of the candidate build — fold ICU's country display names onto the country rows.
  */
 
 import { enumerateCountryDisplayNames } from "@mailwoman/codex/country"
@@ -11,22 +10,13 @@ import type { PlaceAttrs, StageRow } from "#candidate/place-attrs"
 import { normalizeLocalityForKey } from "#street/normalize"
 
 /**
- * Fold every country surface ICU knows onto that country's candidate row (#1678 thread 1).
+ * Stages each country name that `Intl.DisplayNames` renders in the codex display-name
+ * locales as a non-primary key on that country's candidate row.
  *
- * A bare `格鲁吉亚` (Georgia the country) resolved to NOTHING while `佐治亚州` (Georgia the US state) resolved correctly, and
- * the model gave both the same wrong `locality` tag — so the tag was never the variable. Measured 2026-08-15: 140 of
- * 237 country rows are synthetic and carry a canonical English name and nothing else; WOF holds no Chinese country
- * names at all; and the GeoNames alias fold filters through a Latin-script regex, so neither existing source could ever
- * supply them.
+ * The row's display name is unchanged, so a query such as `格鲁吉亚` resolves to the existing Georgia row.
+ * When several country rows share an ISO code, the most populous one receives the keys.
  *
- * `Intl.DisplayNames` already knows every one — ~280 regions, ~5,244 surfaces, from the same ICU the runtime uses for
- * every other locale-sensitive operation. No download, no vendored corpus, no snapshot to drift.
- *
- * `is_primary = 0`: these are NAMES THE WORLD USES, not the country's canonical name. The display `name` stays whatever
- * the gazetteer already had, so resolving `格鲁吉亚` answers with the Georgia country row rather than renaming it.
- *
- * Returns the row count so the caller can report it — a zero means ICU supplied nothing, which is a different fact from
- * the pass not having run.
+ * @returns The number of rows staged.
  */
 export function stageCountryDisplayNames(ctx: {
 	attrs: Map<number, PlaceAttrs>
@@ -35,8 +25,6 @@ export function stageCountryDisplayNames(ctx: {
 	stageRow: StageRow
 	tx: { exec(sql: string): void }
 }): number {
-	// One country row per ISO2. Where a code has several (historic rows surviving the is_current filter), the most
-	// populous wins — the same tiebreak the ranking uses everywhere else.
 	const countryByISO2 = new Map<string, { sid: number; a: PlaceAttrs }>()
 
 	for (const [sid, a] of ctx.attrs) {
@@ -48,7 +36,7 @@ export function stageCountryDisplayNames(ctx: {
 
 		const held = countryByISO2.get(iso2)
 
-		if (!held || a.pop > held.a.pop) {
+		if (!held || (a.pop ?? 0) > (held.a.pop ?? 0)) {
 			countryByISO2.set(iso2, { sid, a })
 		}
 	}
@@ -64,8 +52,6 @@ export function stageCountryDisplayNames(ctx: {
 
 		const k = normalizeLocalityForKey(name)
 
-		// The country's own key is already staged as its primary; INSERT OR IGNORE at materialization dedupes the
-		// rest, so this only skips the obvious self-alias.
 		if (!k || k === target.a.pkey) continue
 
 		ctx.stageRow(k, target.a, target.sid, 0)

package/lib/candidate/extract-fold.ts

@@ -2,27 +2,18 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- * @file Pass 4 of the candidate build — fold a postcode or locality extract into the staging table.
  */
 
 import { DatabaseClient } from "@mailwoman/sqlite/client"
 import { tableExists } from "@mailwoman/sqlite/introspection"
+import type { PathBuilderLike } from "path-ts"
 
-import { CANDIDATE_ANCESTOR_COLUMNS, CANDIDATE_ANCESTOR_TABLE } from "#candidate-ancestors-schema"
-import type { CandidateDatabase } from "#candidate-schema"
+import { CANDIDATE_ANCESTOR_COLUMNS, CANDIDATE_ANCESTOR_TABLE } from "#candidate/ancestors/schema"
 import type { PlaceAttrs, StageRow } from "#candidate/place-attrs"
+import type { CandidateDatabase } from "#candidate/schema"
 import type { WOFDatabase } from "#schema"
 import { normalizeLocalityForKey } from "#street/normalize"
 
-/**
- * The extract's own region-tier ancestry, when it carries any: extract id → the admin region's id. A locality extract
- * derived from a national register (the Taiwanese 鄉鎮市區 from the civil-affairs address points) knows which 縣市 each row
- * belongs to, and writes that as an `ancestors` row against the admin region's WOF id. Without it a folded row has no
- * region scope, so a `parentID`-scoped probe misses it and the cascade widens to whatever namesake carries the key.
- *
- * Only a region the admin build staged (`attrs`) counts: an id the admin does not know cannot be denormalized into a
- * closure row, and a scope nothing can match would be a silent zero rather than an absence.
- */
 function extractRegionAncestry(pc: DatabaseClient<WOFDatabase>, attrs: Map<number, PlaceAttrs>): Map<number, number> {
 	const regionOf = new Map<number, number>()
 
@@ -46,28 +37,21 @@ function extractRegionAncestry(pc: DatabaseClient<WOFDatabase>, attrs: Map<numbe
 }
 
 /**
- * Fold ONE extract (`spr` rows at `extractPlacetype` carrying real coordinates) in, then pass 4b: the alias names
- * hanging off that same extract's `names` table.
+ * Stages one postcode or locality extract's located `spr` rows and their `names`
+ * aliases into the candidate table.
  *
- * Self-contained by construction — it shares only the staging statement and the code dictionaries with the admin passes
- * above it, and nothing downstream reads anything it produces except the counters it returns. The one thing it writes
- * beyond the staging table is a depth-1 closure row for a row whose extract names its region (see
- * {@link extractRegionAncestry}), so the pick's stamped ancestors agree with the scope it was found under.
+ * When `attrs` is given and the extract's `ancestors` table places a row in a known region,
+ * the row also gets that region's scope and the region's ancestor chain.
+ * The stored ancestors then agree with the row's scope.
  */
 export function foldExtract(ctx: {
-	/**
-	 * The staging connection. The extract itself is opened read-only here and closed before returning.
-	 */
 	out: DatabaseClient<CandidateDatabase>
-	extractPath: string
+	extractPath: PathBuilderLike
 	extractPlacetype: "postalcode" | "locality"
 	ccID: (code: string | null) => number
 	ptID: (pt: string | null) => number
 	stageRow: StageRow
-	/**
-	 * The admin places pass 1 staged — what an extract's region ancestry is resolved against. Absent, no extract row
-	 * takes a region scope (the postcode extracts, which carry none).
-	 */
+
 	attrs?: Map<number, PlaceAttrs>
 	progress: (phase: string, message: string) => void
 }): { primaries: number; aliases: number; scoped: number; ancestorRows: number } {
@@ -77,8 +61,7 @@ export function foldExtract(ctx: {
 
 	using pc = new DatabaseClient<WOFDatabase>(extractPath, { readOnly: true })
 	const pcPtid = ptID(extractPlacetype)
-	// Per-extract, not the admin `attrs` map: pass 1 only ever sees the admin DB, so the alias pass
-	// below has nothing to join against unless this primary loop records what it staged.
+
 	const pcAttrs = new Map<number, PlaceAttrs>()
 	const regionOf = ctx.attrs ? extractRegionAncestry(pc, ctx.attrs) : new Map<number, number>()
 
@@ -86,10 +69,6 @@ export function foldExtract(ctx: {
 		`INSERT OR IGNORE INTO ${CANDIDATE_ANCESTOR_TABLE} VALUES (${CANDIDATE_ANCESTOR_COLUMNS.map(() => "?").join(", ")})`
 	)
 
-	// The region's own closure rows, as the sidecar pass wrote them. A scoped row inherits the whole chain above its
-	// region — macroregion, country — not the region alone: the widened-scope refusal reads a pick's stamped ancestors
-	// against the parent the walk resolved, and a 縣市 that resolves to its macroregion record (`桃園市`, which WOF names
-	// only at that tier) would otherwise contradict a lineage that stops at the region.
 	const regionChain = out.prepare(
 		`SELECT depth, parent_spr_id, parent_placetype_id, parent_name, parent_name_key FROM ${CANDIDATE_ANCESTOR_TABLE} WHERE spr_id = ? ORDER BY depth`
 	)
@@ -118,9 +97,6 @@ export function foldExtract(ctx: {
 		const id = Number(r.id)
 		const rid = regionOf.get(id) ?? 0
 
-		// region_id from the extract's own ancestry when it names one, else 0 (a postcode is unique by
-		// name+country — no same-name disambiguation); neg_rank 0 (no population). bbox = the row's own
-		// min/max (falls back to the centroid point).
 		const a: PlaceAttrs = {
 			cid: ccID(r.country as string | null),
 			rid,
@@ -135,9 +111,7 @@ export function foldExtract(ctx: {
 			pop: 0,
 			neg: 0,
 			pkey: key,
-			// A postcode has no toponym fame — nobody writes an encyclopedia article about SW1A 2AA — and
-			// the score source carries no `postalcode` rows to join against anyway. NULL is the truthful
-			// value: unmeasured, so the ranking key leaves postcode rows exactly where they were.
+
 			imp: null,
 		}
 
@@ -172,20 +146,6 @@ export function foldExtract(ctx: {
 
 	out.exec("COMMIT")
 
-	// --- pass 4b: postcode ALIAS names (#1495) ---
-	//
-	// The delivery-city names GeoNames supplies for a ZIP ("Brooklyn" for 11201) are written into
-	// the extract's `names` table by `postcode/centroid-fills.ts`'s `geonamesNameFill`. Everything
-	// downstream of `names` picked them up EXCEPT this build: `fts.ts` unions `spr.name` with every
-	// `names` row into `place_search.alt_names`, so the FTS backend resolved "Brooklyn" → 11201
-	// while the candidate backend — whose every row IS an exact-tier row — had no key for it at
-	// all. Pass 2 does the equivalent fold for admin places, but reads the ADMIN `place_search`,
-	// and `attrs` holds admin ids only, so a postcode extract could never reach it.
-	//
-	// Same discipline as pass 2: `is_primary = 0` (so `rankByPrimaryPreference` treats it as an
-	// alias, not a canonical postcode name), the row stays denormalized onto the POSTCODE's own
-	// spr_id/coords/bbox, and the display `name` stays the postcode — resolving "brooklyn" answers
-	// with place 11201, it does not rename the place to its delivery city.
 	const hasNames = tableExists(pc, "names")
 
 	if (hasNames) {
@@ -198,8 +158,6 @@ export function foldExtract(ctx: {
 
 			const k = normalizeLocalityForKey(String(r.name ?? ""))
 
-			// The postcode's own key is already staged as the primary; `INSERT OR IGNORE` at
-			// materialization dedupes repeats, so this only skips the obvious self-alias.
 			if (!k || k === a.pkey) continue
 
 			stageRow(k, a, Number(r.id), 0)
@@ -209,9 +167,6 @@ export function foldExtract(ctx: {
 
 		out.exec("COMMIT")
 	} else {
-		// Never a silent zero: real extracts come from `createUnifiedSchema`, which always creates
-		// `names`. A extract without it has no alias surface to lose, but say so rather than reporting
-		// "0 aliases" from a table that was never read.
 		progress("postcode-aliases", `${extractPath} has no \`names\` table — no delivery-city aliases to fold`)
 	}
 

package/lib/candidate/fts.ts

@@ -0,0 +1,28 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   FTS5-trigram fuzzy index over the candidate gazetteer's normalized `name_key`; raw SQL on purpose, since Kysely cannot express `create virtual table … using fts5`.
+ */
+
+import type { DatabaseClient } from "@mailwoman/sqlite/client"
+
+/**
+ * Name of the FTS5 trigram virtual table this module owns, on which the reader
+ * conditions its fuzzy fallback.
+ */
+export const CANDIDATE_FTS_TABLE = "candidate_fts"
+
+/**
+ * Build (or rebuild) {@link CANDIDATE_FTS_TABLE} from the materialized `candidate` table. call
+ * after the candidate B-tree is populated or against an existing candidate DB.
+ */
+export function createCandidateFTS<DB>(db: DatabaseClient<DB>): void {
+	db.exec(`DROP TABLE IF EXISTS ${CANDIDATE_FTS_TABLE}`)
+	db.exec(`CREATE VIRTUAL TABLE ${CANDIDATE_FTS_TABLE} USING fts5(name_key, tokenize='trigram')`)
+
+	db.exec(
+		`INSERT INTO ${CANDIDATE_FTS_TABLE}(name_key) SELECT DISTINCT name_key FROM candidate WHERE name_key IS NOT NULL`
+	)
+}

package/lib/candidate/importance.ts

@@ -0,0 +1,221 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The score side of the candidate build: load a WOF admin database's `place_importance` into a
+ *   lookup the candidate builder probes per place, so every candidate row can include the
+ *   toponym-fame prior a bare city name is decided on.
+ *
+ *   The join key is `(name_key, country, placetype)`, the same {@link normalizeLocalityForKey} the
+ *   candidate build uses for its probe key, so the two sides fold identically. An id join is wrong
+ *   here, because the score source (`admin-global-priority-importance.db`) and the candidate build's
+ *   admin source are different snapshots whose ids disagree. An id join silently drops rows and
+ *   leaves the ranking inert on the queries the prior exists for.
+ *
+ *   The key by itself is not enough. `(warwick, US, locality)` covers eleven different places.
+ *   The group's maximum would give every Warwick in America the fame of Warwick, Rhode Island.
+ *   The join picks the nearest centroid when it falls within {@link IMPORTANCE_JOIN_RADIUS_KM}.
+ *   Two artifacts describing the same settlement put its centroid
+ *   in almost the same place. Two towns with the same name in one country do not.
+ *
+ *   `place_importance.importance` lands in the column verbatim, the pre-split conflation that is
+ *   encyclopedia-derived where the concordance matched and a population-derived proxy everywhere
+ *   else. See {@link CandidateTable.importance} for why the split `encyclopedic` channel is not what
+ *   is written here.
+ *
+ *   A place with no match gets NULL. NULL means the place's fame is unmeasured.
+ *   The consumer (`resolver/toponym-prior.ts`) leaves an unmeasured candidate at the position
+ *   population assigned it.
+ */
+
+import { haversineKm } from "@mailwoman/spatial"
+import { DatabaseClient } from "@mailwoman/sqlite/client"
+import type { PathBuilderLike } from "path-ts"
+
+import type { CandidateDatabase } from "#candidate/schema"
+import { normalizeLocalityForKey } from "#street/normalize"
+
+/**
+ * How far apart two artifacts may put the same place's centroid and still be read as the same place.
+ *
+ * Measured from two admin snapshots.
+ * The nearest-centroid distances separate into a mode where the two snapshots agree
+ * and a background rate of two different towns wearing one name in one country.
+ *
+ * The background rate does not decay with distance.
+ * Ten kilometers separates the two populations.
+ *
+ * That distance matches the join's purpose.
+ * A radius above the floor starts handing one town's fame to another.
+ */
+export const IMPORTANCE_JOIN_RADIUS_KM = 10
+
+/**
+ * One scored place from the source, with its coordinates and importance score.
+ */
+interface ScoredPlace {
+	lat: number
+	lon: number
+	importance: number
+}
+
+/**
+ * What {@link loadImportanceIndex} measured while reading the source.
+ *
+ * Reported by the builder so a run reports how much of the gazetteer it actually scored,
+ * rather than leaving the caller to infer it from a column full of nulls.
+ */
+export interface ImportanceIndexStats {
+	/**
+	 * Scored places read out of the source.
+	 */
+	places: number
+	/**
+	 * Distinct `(name_key, country, placetype)` groups they fall into.
+	 */
+	keys: number
+	/**
+	 * Places whose name folded to the empty key and could never be joined
+	 * (non-Latin punctuation-only names, blanks).
+	 */
+	unkeyable: number
+}
+
+/**
+ * `(name_key, country, placetype)` → the scored places under it.
+ *
+ * The separator is U+0000, a character no WOF name contains and no fold can produce,
+ * so the three fields cannot smear into one another.
+ */
+function groupKey(nameKey: string, country: string | null, placetype: string | null): string {
+	return `${nameKey}\u0000${(country ?? "").toUpperCase()}\u0000${placetype ?? ""}`
+}
+
+/**
+ * A loaded `place_importance`, probed by name + country + placetype + position.
+ */
+export class ImportanceIndex {
+	readonly #groups: Map<string, ScoredPlace[]>
+	readonly stats: ImportanceIndexStats
+	/**
+	 * Places {@link find} matched inside the radius.
+	 */
+	matched = 0
+	/**
+	 * Places {@link find} refused.
+	 *
+	 * The key matched a scored group, but the nearest member was outside the radius,
+	 * so it is a different place wearing the same name.
+	 *
+	 * This is the number worth watching across rebuilds.
+	 * A jump means the score source and the admin source have drifted apart
+	 * and the join is being asked to guess.
+	 * It does not mean the radius is too tight.
+	 */
+	refused = 0
+
+	constructor(groups: Map<string, ScoredPlace[]>, stats: ImportanceIndexStats) {
+		this.#groups = groups
+		this.stats = stats
+	}
+
+	/**
+	 * The importance of the scored place nearest `(lat, lon)` sharing `name`'s folded key, `country`
+	 * and `placetype`, or null when there is no such place within {@link IMPORTANCE_JOIN_RADIUS_KM}.
+	 *
+	 * Null is unmeasured.
+	 * Keep the value null.
+	 * Do not substitute zero or a population-derived value here.
+	 *
+	 * The source column already contains a population-derived fallback where one exists.
+	 * A second fallback would make an absence indistinguishable from a measurement.
+	 */
+	find(name: string, country: string | null, placetype: string | null, lat: number, lon: number): number | null {
+		const nameKey = normalizeLocalityForKey(name)
+
+		if (!nameKey) return null
+
+		const group = this.#groups.get(groupKey(nameKey, country, placetype))
+
+		if (!group) return null
+
+		let best: ScoredPlace | undefined
+		let bestKm = Infinity
+
+		for (const place of group) {
+			const km = haversineKm(lat, lon, place.lat, place.lon)
+
+			if (km < bestKm) {
+				bestKm = km
+				best = place
+			}
+		}
+
+		if (!best || bestKm > IMPORTANCE_JOIN_RADIUS_KM) {
+			this.refused++
+
+			return null
+		}
+
+		this.matched++
+
+		return best.importance
+	}
+}
+
+/**
+ * Read `place_importance` from a WOF admin database and join it to `spr`.
+ *
+ * The join retrieves each place's name, country, placetype, plus its centroid.
+ * These fields populate an {@link ImportanceIndex}.
+ *
+ * Only current, non-deprecated places are indexed.
+ * A superseded row's score belongs to a place the gazetteer no longer contains.
+ *
+ * If that row won the nearest-centroid contest, a live place would inherit the superseded place's fame.
+ *
+ * The whole table is held in memory on purpose, because the build probes it once for every place
+ * and the alternative is a prepared statement per place against a multi-gigabyte database.
+ */
+export function loadImportanceIndex(databasePath: PathBuilderLike): ImportanceIndex {
+	using db = new DatabaseClient<CandidateDatabase>(databasePath, { readOnly: true })
+
+	const groups = new Map<string, ScoredPlace[]>()
+	let places = 0
+	let unkeyable = 0
+
+	for (const row of db
+		.prepare(
+			`SELECT s.name AS name, s.country AS country, s.placetype AS placetype,
+				s.latitude AS latitude, s.longitude AS longitude, i.importance AS importance
+			 FROM place_importance i JOIN spr s ON s.id = i.id
+			 WHERE s.is_current != 0 AND s.is_deprecated = 0`
+		)
+		.iterate()) {
+		const importance = Number(row.importance)
+
+		if (!Number.isFinite(importance)) continue
+		const nameKey = normalizeLocalityForKey(String(row.name ?? ""))
+
+		if (!nameKey) {
+			unkeyable++
+
+			continue
+		}
+
+		const key = groupKey(nameKey, row.country as string | null, row.placetype as string | null)
+		let group = groups.get(key)
+
+		if (!group) {
+			group = []
+			groups.set(key, group)
+		}
+
+		group.push({ lat: Number(row.latitude), lon: Number(row.longitude), importance })
+
+		places++
+	}
+
+	return new ImportanceIndex(groups, { places, keys: groups.size, unkeyable })
+}